본문으로 바로가기

배포했는데 사용자 화면은 그대로? 정적 JS 캐시 전략 4가지 비교

레거시 jQuery 뷰어를 Nuxt로 옮긴 뒤 배포해도 휴대폰에서는 예전 동작이 계속 보였습니다. 주소가 고정된 /libs 스크립트에 Cache-Control이 없어 브라우저 휴리스틱 캐시가 옛 파일을 재사용한 것이 원인이었습니다. 기존, gzip/brotli 압축, 빌드 ID 쿼리, no-cache 네 방식을 실측으로 비교하고 no-cache와 압축을 함께 쓰기로 한 이유, 그리고 헤더를 바꿔도 이미 받은 파일에는 적용되지 않는 전환 시점의 함정까지 정리했습니다.

· · 9분 읽기

목차
  1. 1. 문제 상황
  2. 2. 원인: 주소가 고정된 정적 파일 + 캐시 헤더 없음
  3. 3. 측정 대상: 뷰어 라이브러리 7개
  4. 4. 네 가지 방식
  5. 5. 비교 (사용자 1명 기준, 뷰어 1회 열기)
  6. 6. 선택:
  7. 7. 함정: 헤더를 바꿔도 이미 받은 파일에는 적용되지 않는다
  8. 8. 남은 과제 / 더 나은 장기안

레거시 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). 같은 코드를 다시 빌드해 배포해도 다시 받는다.
    • 파일마다 내용 해시를 붙이면 해결되지만, 해시를 계산해 주입하는 빌드 단계를 직접 만들어야 한다.
    • 코드 변경이 필요하다. 스크립트를 불러오는 플러그인에서 주소를 만드는 부분을 고쳐야 한다.

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 압축

이유:

  1. 최신 반영이 보장된다. 이번 문제를 근본적으로 막는다.
  2. 데이터를 가장 적게 쓴다. 바뀐 파일만, 압축해서 받는다. 이번 같은 배포라면 438 KB 대신 23.8 KB다.
  3. 설정 두 줄로 끝난다. 레거시 라이브러리나 로딩 코드를 건드리지 않아 위험이 가장 적다.
  4. 빌드 ID 방식의 장점(재방문 시 요청 0개)은 확인 요청 7개를 아끼는 정도다. 매 배포마다 바뀌지 않은 파일까지 103 KB를 다시 받는 비용보다 작다고 판단했다.

적용할 설정(nuxt.config.ts):

TypeScript
export default defineNuxtConfig({
  nitro: {
    // 빌드 시 .gz/.br 를 미리 만들어 Accept-Encoding 에 맞춰 내려준다
    compressPublicAssets: true
  },
  routeRules: {
    // 레거시 뷰어 라이브러리는 주소가 고정이라, 매번 ETag 로 확인해 바뀐 파일만 받게 한다
    '/libs/**': { headers: { 'cache-control': 'no-cache' } }
  }
})

로컬 운영 빌드에서 확인한 결과:

Text
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 는 이 지시가 없던 시절에 받은 응답이다. 그래서 브라우저는 그 파일에 대해 여전히 휴리스틱 캐시 규칙을 따른다. 유효 기간이 끝날 때까지는 서버에 묻지도 않으니, 새 헤더가 있다는 사실조차 모른다.

Text
[과거] GET /libs/viewer.js → 200 (Cache-Control 없음, Last-Modified: 석 달 전)
        → 브라우저: "약 9일은 그냥 써도 되겠다" (휴리스틱)
[배포] 서버는 이제 no-cache 를 붙여서 응답한다
[오늘] 뷰어 열기 → 브라우저: "아직 9일 안 지났으니 저장본 사용" → 서버에 요청 안 함
        → 새 헤더도, 새 파일도 못 받음

즉 no-cache 는 앞으로 받을 파일을 위한 설정이다. 이미 받아 둔 파일을 소급해서 바꾸지는 못한다.

해결: 전환 시점에 딱 한 번만 주소를 바꾼다

브라우저 캐시는 주소(URL) 단위로 저장된다. 그래서 주소가 달라지면 브라우저는 저장본이 없다고 보고 새로 받는다. 스크립트를 불러오는 플러그인에 버전 쿼리를 한 번 붙였다.

TypeScript
// /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 와 압축이 그대로 적용된다.

Text
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

배포 후 흐름

  1. 배포 직후 첫 방문: 새 페이지가 ?v=2 주소로 스크립트를 부른다. 기존 사용자도 신규 사용자도 새 파일을 한 번 받는다. 옛 캐시 문제는 여기서 끝난다.
  2. 그 이후 방문: 뷰어를 열 때마다 바뀌었는지만 확인한다. 안 바뀌었으면 304, 바뀌었으면 그 파일만 압축해서 받는다.
  3. 이후 /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 없음).

최성호

프론트엔드 엔지니어. SVG, Three.js, 인터랙션 UI, 에디터 구조를 다룹니다.

소개 보기

댓글

GitHub 계정으로 의견을 남길 수 있습니다.