홈 화면 사이트가 옛 버전으로 뜰 때

결론부터

• 홈 화면 아이콘은 앱이 아니라 바로가기입니다. 누르면 사이트를 다시 여는 것이라, 사이트를 고치면 그대로 반영되는 게 정상입니다. 막는 건 캐시(휴대폰에 저장해 둔 파일)입니다.
• 원인 — Cloudflare의 Browser Cache TTL(브라우저 캐시 유지 시간)이 4시간으로 설정돼 있어서, "매번 확인하라"고 적어 둔 게임 파일도 4시간짜리로 바뀌어 나갔습니다.
• 해결 — 게임 파일 주소 끝에 내용이 바뀔 때마다 달라지는 꼬리표(game.js?v=4b6c73c540)를 붙였습니다. 주소가 바뀌면 휴대폰은 저장된 파일을 쓰지 않고 새로 받습니다.

값은 실제 사이트의 응답 헤더를 읽어 확인했습니다. 게임 파일은 max-age=0으로 정해 두었는데 max-age=14400(14400초 = 4시간)으로 나가고 있었습니다.

왜 HTML은 되고 자바스크립트는 안 됐나

Cloudflare는 HTML 페이지는 기본적으로 중간에 저장하지 않고 그대로 전달합니다(응답 헤더에 cf-cache-status: DYNAMIC). 그래서 페이지에 적어 둔 "매번 확인(max-age=0)"이 휴대폰까지 그대로 갑니다.

반면 .js, .jpg 같은 파일은 Cloudflare가 저장해 두고 나눠 주는 대상입니다. 이 파일들에는 도메인 설정의 Browser Cache TTL이 적용되는데, 제가 적어 둔 값(0초)보다 설정값(4시간)이 길면 설정값으로 바꿔서 내보냈습니다.

결과적으로 페이지는 새 버전인데 게임 본체는 옛 버전인 상태가 최대 4시간 동안 생길 수 있었습니다. 둘이 어긋나면 화면이 깨지거나 고친 내용이 안 보입니다.

해결 — 파일 주소에 버전 꼬리표 붙이기

캐시를 아예 끄면 매번 750KB짜리 게임 파일을 다시 받아야 합니다. 대신 내용이 바뀔 때만 주소가 바뀌게 했습니다.

1. 게임을 빌드할 때 game.js 내용으로 지문(해시)을 계산합니다. 내용이 한 글자라도 바뀌면 지문도 바뀝니다.
2. 페이지(HTML)에서 게임 파일을 부르는 주소 끝에 그 지문을 붙입니다. <script src="game.js?v=4b6c73c540">
3. 페이지는 매번 새로 확인되므로, 게임을 고치면 휴대폰은 새 주소를 보게 되고 새 파일을 받습니다. 안 고쳤으면 주소가 같으니 저장된 파일을 그대로 써서 빠릅니다.

빌드 스크립트에 넣은 한 줄은 이렇습니다.

V=$(sha256sum dist/game.js | cut -c1-10); sed -i "s#src=\"game.js\"#src=\"game.js?v=$V\"#" dist/index.html

휴대폰에서 바로 새 버전 보기

꼬리표를 붙이기 전에 올린 옛 파일이 남아 있을 수 있습니다. 한 번만 아래처럼 하면 됩니다.

1. 홈 화면 아이콘으로 연 화면을 앱 전환 화면에서 위로 밀어 완전히 닫습니다.
2. 다시 아이콘을 눌러 엽니다. 그래도 옛 화면이면 브라우저 앱(사파리·크롬)에서 같은 주소를 열고 새로 고칩니다.

꼬리표를 붙인 뒤부터는 이 과정 없이 고칠 때마다 새 버전이 뜹니다.

배운 것

• 설정한 값과 실제로 나간 값은 다를 수 있다. 파일에 "0초"라고 적었어도 중간 서비스 설정이 덮어쓸 수 있으니, 브라우저 개발자 도구(F12) → Network 탭에서 응답 헤더를 직접 봐야 합니다.
• 캐시는 끄지 말고 주소로 관리한다. 내용이 바뀌면 주소가 바뀌게 하면 빠르기와 최신이 둘 다 됩니다.
• 페이지(HTML)만은 매번 확인되게 둔다. 꼬리표가 바뀐 걸 알려 주는 게 페이지이기 때문입니다.

게임은 스카이라인 스윙에서 해 볼 수 있습니다.

참고한 자료

• Cloudflare Browser Cache TTL (공식 문서)