배포했는데 옛날 화면이 떠요: 캐시가 새 페이지와 옛 파일을 섞을 때

hbc studio · 작업한 때 2026년 10월 5일 ~ 9일 · 기록 2026년 10월 16일

hbc studio의 웹 서비스들은 모두 Cloudflare Pages에 올라가 있어요. 그런데 한 주 사이에 서로 다른 세 서비스에서 같은 종류의 문제가 생겼어요. 배포를 했는데, 어떤 사람에게는 새 페이지와 옛날 파일이 섞여서 보이는 문제예요.

깜빡: 새 HTML, 옛 스크립트

깜빡을 고쳐 올린 직후, 인스타그램과 카카오톡 안에서 링크를 연 사람들의 화면이 이상해졌어요. 숨겨 둔 제목이 다시 보이고, 스크립트는 이미 지운 버튼을 찾다가 멈췄어요.

원인은 캐시 시간이 파일마다 달랐던 거예요. Cloudflare는 페이지(HTML)는 매번 새로 받게 하면서, CSS와 자바스크립트는 브라우저가 4시간 동안 보관하게 했어요. 그래서 최근 4시간 안에 들어온 적이 있는 브라우저는 새 HTML과 옛 CSS·스크립트를 함께 쓰게 된 거예요. 인앱 브라우저는 자기만의 캐시를 갖고 있어서 이 문제가 특히 잘 드러났어요.

해결은 파일 주소에 내용의 지문을 붙이는 거였어요. css/style.css?v=5f6622d6처럼 파일 내용으로 만든 짧은 해시를 붙이면, 파일이 바뀌는 순간 주소도 바뀌니 브라우저가 옛 파일을 쓸 수가 없어요. 이 값은 스크립트(scripts/stamp.js)가 써 넣고, 해시가 실제 파일과 맞지 않으면 테스트가 실패하게 해서 깜빡 잊고 배포하는 일을 막았어요.

honeybeecook.com: 같은 이름, 다른 그림

같은 날 이 사이트의 첫 화면, 꿀이 흘러내리는 애니메이션을 가볍게 바꿨어요. 150장의 프레임을 꿀이 있는 부분만 남기고 잘라 냈고, 그리는 코드도 잘린 프레임에 맞게 고쳤어요. 그런데 프레임 파일 이름은 그대로였어요. 최근에 방문한 휴대폰은 캐시에 남은 옛날 전체 크기 프레임을 새 그리기 코드로 그리게 되는 상황이었죠.

그래서 프레임 주소에 프레임 묶음의 이름을 붙였어요(?v=crop576x1040). 프레임이 바뀌면 이 이름도 바꾸라고 코드 옆에 적어 두었어요.

1분게임: 스크립트 자리에 온 HTML

나흘 뒤 1분게임에서는 더 심한 일이 있었어요. 화면이 하얗게만 나오는 거예요. 확인해 보니 Cloudflare의 엣지 서버가 스크립트 세 개를 달라는 요청에 첫 화면 HTML을 대신 돌려주고 있었어요. 배포가 진행되는 도중에 들어온 요청이 HTML을 받았고, 그 응답에 “1년 동안 바뀌지 않음(immutable)”이라는 헤더가 붙어 있어서 그 잘못된 응답이 그대로 굳어 버린 거예요.

빌드 결과물이 매번 다시 확인되도록 캐시 헤더를 바꾸고, 파일을 새 해시 이름으로 옮겨서 고쳤어요. 이미 굳어 버린 옛 주소를 아무도 다시 요청하지 않게 된 거죠.

배운 것

• HTML과 그 HTML이 부르는 파일의 캐시 시간이 다르면, 언젠가는 둘이 섞여요. 파일 주소에 내용의 지문을 넣는 게 가장 확실해요.
• “이 파일은 영원히 안 바뀐다”는 약속은 그 주소에 엉뚱한 내용이 담겼을 때 그대로 독이 돼요.
• 인앱 브라우저(카카오톡, 인스타그램 등)는 일반 브라우저와 따로 캐시를 들고 있어서, 문제를 먼저, 더 자주 보여 줘요. 링크 공유가 많은 서비스라면 테스트 목록에 꼭 넣어야 해요.