레거시 jQuery 뷰어를 Nuxt 4 앱으로 옮긴 뒤, 수정 사항을 배포했는데도 일부 휴대폰에서 예전 동작이 계속 보였다. 원인을 추적하고 기존 / gzip 압축 / 빌드 ID 붙이기 / no-cache 네 가지 방식을 실측해 비교했다.
- 작성일: 2026-11-03
- 대상: 회사 프론트엔드(Nuxt 4.5, Nitro node-server)의 웹 뷰어 페이지
- 측정 방식: 운영 서버 응답 헤더 확인 + 로컬 운영 빌드(
pnpm build→node .output/server/index.mjs)에서 설정을 바꿔 가며curl로 측정
1. 문제 상황
뷰어 버그 몇 가지를 고쳐 배포했다. 그런데 휴대폰에서 열어 보니 다음과 같았다.
- 상단 바의 파트너명이 사라진 CSS 수정은 반영됨
- 잡지가 아래로 치우쳐 보이는 문제, 확대 후
<>버튼이 안 되는 문제는 예전 그대로
git 브랜치(main / origin/main / origin/dev)도 모두 최신이었다. 운영 서버의 /libs/viewer.js · /libs/zoom.js 내용에도 수정 코드가 들어 있었다. 서버는 새것인데 화면만 예전 것인 상황이다.
2. 원인: 주소가 고정된 정적 파일 + 캐시 헤더 없음
이 앱의 JS는 두 종류다.
| 구분 | 예시 주소 | 서버 응답 캐시 헤더 | 배포 후 동작 |
|---|---|---|---|
| Nuxt(Vite)가 만든 화면 코드 | /_nuxt/D255EP6g.js |
public, max-age=31536000, immutable |
파일 이름에 내용 해시가 들어가 배포마다 주소가 바뀜 → 항상 새 파일 |
| 레거시 뷰어 라이브러리 | /libs/viewer.js |
없음 (ETag, Last-Modified 만) |
주소가 항상 같음 → 브라우저가 예전 파일을 재사용할 수 있음 |
레거시 jQuery 라이브러리 7개(jquery, swiper, turn, zoom, hammer, hash, viewer)는 public/libs/ 에 두고 플러그인에서 <script src="/libs/viewer.js"> 로 불러온다.
Cache-Control 이 없으면 브라우저는 휴리스틱 캐시를 쓴다. Last-Modified 로부터 지난 시간의 약 10% 동안은 서버에 묻지 않고 캐시를 그대로 쓴다. 예를 들어 석 달 동안 안 바뀐 파일이면 약 9일 동안 다시 확인하지 않는다. 그래서 새 CSS(해시 주소)와 옛 JS(고정 주소)가 섞인 화면이 나왔다.
3. 측정 대상: 뷰어 라이브러리 7개
| 파일 | 원본 | gzip | brotli |
|---|---|---|---|
| jquery.min.js | 88,151 B | 30,657 B | 27,747 B |
| swiper.min.js | 140,929 B | 35,760 B | 31,060 B |
| turn.js | 76,136 B | 17,983 B | 15,495 B |
| viewer.js | 85,772 B | 20,763 B | 17,630 B |
| zoom.js | 33,639 B | 7,130 B | 6,126 B |
| hammer.min.js | 20,765 B | 7,370 B | 6,561 B |
| hash.js | 2,967 B | 1,081 B | 918 B |
| 합계 | 448,359 B (≈438 KB) | 120,744 B (≈118 KB) | 105,537 B (≈103 KB) |
운영 서버는 지금 이 파일들을 압축 없이 보낸다. 응답에 Content-Encoding 헤더가 없다.
4. 네 가지 방식
4-1. 기존 (설정 없음)
- 동작: 휴리스틱 캐시. 언제 새 파일을 받을지 브라우저가 정한다.
- 장점: 손댈 것이 없다. 캐시가 살아 있는 동안은 요청도 없다.
- 단점: 배포가 언제 반영될지 보장할 수 없다. 이번 문제의 원인이다. 압축도 안 돼 첫 방문에 438 KB를 받는다.
4-2. gzip / brotli 압축
- 적용:
nuxt.config.ts에nitro: { compressPublicAssets: true }한 줄을 넣는다. 빌드할 때.gz·.br파일을 미리 만들어 두고, 브라우저가 보낸Accept-Encoding에 맞춰 골라 준다. - 실측: 438 KB → gzip 118 KB / brotli 103 KB (약 76% 감소).
- 성격: 캐시 문제와는 무관한, 전송량만 줄이는 방법이다. 이것만으로는 옛 파일 문제가 그대로 남는다. 다른 방식과 함께 쓰는 기본 옵션이다.
4-3. 빌드 ID 붙이기 (/libs/viewer.js?v=<buildId>)
- 적용: 스크립트 주소에 Nuxt 빌드 ID를 쿼리로 붙이고, 긴 캐시(
max-age=1년, immutable)를 준다. - 동작: 배포 전까지는 요청 자체가 없다. 배포하면 주소가 바뀌어 새로 받는다.
- 단점:
- Nuxt 빌드 ID는 빌드마다 새로 만드는 무작위 UUID다(로컬 빌드에서
cefeab0c-…확인). 그래서 jQuery · Swiper처럼 바뀌지 않은 파일도 배포마다 7개 모두 다시 받는다(압축 시 103 KB). 같은 코드를 다시 빌드해 배포해도 다시 받는다. - 파일마다 내용 해시를 붙이면 해결되지만, 해시를 계산해 주입하는 빌드 단계를 직접 만들어야 한다.
- 코드 변경이 필요하다. 스크립트를 불러오는 플러그인에서 주소를 만드는 부분을 고쳐야 한다.
- Nuxt 빌드 ID는 빌드마다 새로 만드는 무작위 UUID다(로컬 빌드에서
4-4. no-cache (Cache-Control: no-cache)
- 적용:
routeRules에'/libs/**': { headers: { 'cache-control': 'no-cache' } }를 넣는다. - 동작:
no-cache는 "저장하지 마라"가 아니라 "쓰기 전에 서버에 확인하라"는 뜻이다. 브라우저는 파일을 저장해 두고, 쓸 때마다If-None-Match: <ETag>로 바뀌었는지만 묻는다.- 안 바뀌었으면 서버가
304 Not Modified로 본문 없이(0바이트) 응답한다(로컬 빌드에서 확인). - 바뀌었으면 그 파일만 새로 받는다.
- 안 바뀌었으면 서버가
- ETag 는 파일 크기와 내용 해시로 만들어진다. 운영과 로컬 빌드에서 같은 파일의 ETag 가
"14f0c-z1IIp5…"로 같았다. 그래서 내용이 안 바뀐 파일은 배포를 해도 다시 받지 않는다. - 단점: 뷰어를 열 때마다 확인 요청 7개가 생긴다. 본문은 0바이트지만 왕복 시간이 든다.
- 지금 운영 서버는 HTTP/1.1(keep-alive)로 응답하고, 이 스크립트들은 원래 하나씩 순서대로 불러온다. 그래서 왕복 7번만큼 뷰어 시작이 조금 늦어질 수 있다.
- 앞단에서 HTTP/2 를 켜면 이 부담이 더 줄어든다.
5. 비교 (사용자 1명 기준, 뷰어 1회 열기)
| 기존 | 압축만 | 빌드 ID + 압축 | no-cache + 압축 | |
|---|---|---|---|---|
| 첫 방문 | 438 KB | 103 KB | 103 KB | 103 KB |
| 재방문 (배포 없음) | 0 (요청 없음) | 0 (요청 없음) | 0 (요청 없음) | 확인 요청 7개, 본문 0 B |
| 배포 후 첫 방문 (이번처럼 viewer.js · zoom.js 만 수정) | 0 — 옛 파일 사용 | 0 — 옛 파일 사용 | 103 KB (7개 전부) | 23.8 KB (바뀐 2개만) |
| 최신 반영 보장 | ✗ | ✗ | ○ | ○ |
| 작업량 | 없음 | 설정 1줄 | 플러그인 코드 수정 + 캐시 헤더 설정 | 설정 1줄 |
| 위험도 | 반영 안 됨 | 거의 없음 | 낮음 | 거의 없음 |
참고로 잡지 한 권은 페이지 이미지만 149장이다. 위 차이는 이미지 몇 장 수준이라, 어느 방식이든 사용자 데이터 부담은 크지 않다.
6. 선택: no-cache + brotli/gzip 압축
이유:
- 최신 반영이 보장된다. 이번 문제를 근본적으로 막는다.
- 데이터를 가장 적게 쓴다. 바뀐 파일만, 압축해서 받는다. 이번 같은 배포라면 438 KB 대신 23.8 KB다.
- 설정 두 줄로 끝난다. 레거시 라이브러리나 로딩 코드를 건드리지 않아 위험이 가장 적다.
- 빌드 ID 방식의 장점(재방문 시 요청 0개)은 확인 요청 7개를 아끼는 정도다. 매 배포마다 바뀌지 않은 파일까지 103 KB를 다시 받는 비용보다 작다고 판단했다.
적용할 설정(nuxt.config.ts):
export default defineNuxtConfig({
nitro: {
// 빌드 시 .gz/.br 를 미리 만들어 Accept-Encoding 에 맞춰 내려준다
compressPublicAssets: true
},
routeRules: {
// 레거시 뷰어 라이브러리는 주소가 고정이라, 매번 ETag 로 확인해 바뀐 파일만 받게 한다
'/libs/**': { headers: { 'cache-control': 'no-cache' } }
}
})
로컬 운영 빌드에서 확인한 결과:
AE=none status=200 enc= cache-control=no-cache size=85772
AE=gzip status=200 enc=gzip cache-control=no-cache size=20763
AE=br, gzip status=200 enc=br cache-control=no-cache size=17630
If-None-Match 재요청 → status=304 bytes=0
7. 함정: 헤더를 바꿔도 이미 받은 파일에는 적용되지 않는다
여기까지 하고 "이제 배포만 하면 끝"이라고 생각했다. 그런데 한 가지가 빠져 있었다.
Cache-Control: no-cache 는 서버가 새로 보내는 응답에 붙는 지시다. 지금 휴대폰에 저장된 옛 viewer.js 는 이 지시가 없던 시절에 받은 응답이다. 그래서 브라우저는 그 파일에 대해 여전히 휴리스틱 캐시 규칙을 따른다. 유효 기간이 끝날 때까지는 서버에 묻지도 않으니, 새 헤더가 있다는 사실조차 모른다.
[과거] GET /libs/viewer.js → 200 (Cache-Control 없음, Last-Modified: 석 달 전)
→ 브라우저: "약 9일은 그냥 써도 되겠다" (휴리스틱)
[배포] 서버는 이제 no-cache 를 붙여서 응답한다
[오늘] 뷰어 열기 → 브라우저: "아직 9일 안 지났으니 저장본 사용" → 서버에 요청 안 함
→ 새 헤더도, 새 파일도 못 받음
즉 no-cache 는 앞으로 받을 파일을 위한 설정이다. 이미 받아 둔 파일을 소급해서 바꾸지는 못한다.
해결: 전환 시점에 딱 한 번만 주소를 바꾼다
브라우저 캐시는 주소(URL) 단위로 저장된다. 그래서 주소가 달라지면 브라우저는 저장본이 없다고 보고 새로 받는다. 스크립트를 불러오는 플러그인에 버전 쿼리를 한 번 붙였다.
// /libs 는 Cache-Control: no-cache 로 매번 ETag 확인한다(nuxt.config routeRules). 그 설정 전에 캐시 지시 없이 받은
// 옛 파일은 브라우저가 서버에 묻지 않고 한동안 재사용하므로, 주소를 한 번 바꿔 새 파일로 받게 한다.
// no-cache 가 이후 변경을 처리하므로 배포마다 올릴 필요는 없다. 같은 문제가 다시 생길 때만 올린다.
const LIBS_VERSION = '2'
function loadScript(src: string): Promise<void> {
return new Promise((resolve, reject) => {
const script = document.createElement('script')
script.src = `${src}?v=${LIBS_VERSION}`
// ...
})
}
4-3의 "빌드 ID 붙이기"와 비슷해 보이지만 성격이 다르다.
| 빌드 ID 붙이기 | 이번 ?v=2 |
|
|---|---|---|
| 주소가 바뀌는 시점 | 배포할 때마다 (자동) | 사람이 값을 올릴 때만 (이번 한 번) |
| 역할 | 캐시 갱신을 주소 변경으로 해결 | 옛 캐시를 한 번 끊는 용도. 이후 갱신은 no-cache 가 담당 |
| 안 바뀐 파일 재다운로드 | 배포마다 발생 | 전환 때 한 번만 |
처음 쓰는 사용자도 ?v=2 주소로 한 번 받을 뿐이라 손해가 없다. 쿼리가 붙어도 routeRules 의 '/libs/**' 는 경로 기준이라 no-cache 와 압축이 그대로 적용된다.
GET /libs/viewer.js?v=2 (Accept-Encoding: br, gzip)
→ 200, cache-control: no-cache, content-encoding: br, vary: Accept-Encoding
GET /libs/viewer.js?v=2 (If-None-Match: <ETag>)
→ 304, 본문 0 B
배포 후 흐름
- 배포 직후 첫 방문: 새 페이지가
?v=2주소로 스크립트를 부른다. 기존 사용자도 신규 사용자도 새 파일을 한 번 받는다. 옛 캐시 문제는 여기서 끝난다. - 그 이후 방문: 뷰어를 열 때마다 바뀌었는지만 확인한다. 안 바뀌었으면 304, 바뀌었으면 그 파일만 압축해서 받는다.
- 이후
/libs수정:?v=를 올리지 않아도 no-cache 가 처리한다.
교훈: 캐시 정책을 바꿀 때는 "앞으로"와 "이미 받은 것"을 따로 생각해야 한다. 새 정책은 새 응답부터 적용되고, 이미 받은 것은 주소를 바꾸는 것 말고는 서버에서 건드릴 방법이 거의 없다.
HTTP 캐시 개념(휴리스틱 캐시, no-cache 와 no-store, ETag/304, Vary)은 HTTP 캐시 정리: 휴리스틱 캐시, no-cache와 no-store, ETag까지에 따로 정리했다.
8. 남은 과제 / 더 나은 장기안
- 장기안 (번들로 편입): 레거시 라이브러리를 Vite 번들로 가져오면
/_nuxt/해시 파일과 같은 방식이 된다. 내용이 바뀔 때만 주소가 바뀌고 1년 캐시(immutable)가 걸린다. 다만 이 라이브러리들은window.$, 전역 함수, 스크립트 로드 순서에 의존하므로 리팩터링 범위가 크다. - 앞단 서버 압축: 압축은 Nitro 대신 앞단(nginx, App Gateway, CDN)에서 켜도 된다. 지금 운영 경로에는 압축하는 앞단이 없는 것으로 보인다(응답에
Content-Encoding없음).