스타일시트 캐시 무효화를 수동 버전 키로 해결한 이유

사소해 보이는 쿼리스트링 한 글자 바꿨는데, 이게 의외로 꽤 중요한 작업이었다.

왜 캐시 키를 올렸냐

styles.css에 스타일 변경을 배포했는데 브라우저가 여전히 이전 버전을 잡고 있었다. 전형적인 캐시 무효화 문제. CDN이나 브라우저 캐시가 파일 URL이 동일하면 내용을 다시 받지 않으려 하는 건 당연한 동작이고, 오히려 그게 정상적으로 동작하고 있다는 증거기도 하다. 문제는 그 "정상 동작"이 배포 직후 사용자 경험을 망치는 타이밍에 발동한다는 거다.

Base.astro는 레이아웃 최상단 파일이라서 모든 페이지에 공통으로 적용되는 CSS 링크를 여기서 주입하고 있다. 이 파일 하나만 건드리면 전체 페이지의 스타일시트 로딩 전략이 바뀌는 구조다. 변경 파일이 딱 하나인 이유가 그거다.

<!-- before -->
<link rel="stylesheet" href="/styles.css?v=20260515a" />

<!-- after -->
<link rel="stylesheet" href="/styles.css?v=20260515b" />

패턴 자체는 단순하다. 파일 이름은 그대로 두고 쿼리스트링만 바꿔서 브라우저가 "새 URL = 새 파일"로 인식하게 강제하는 방식이다. 오늘 날짜에 b를 붙인 건 같은 날 두 번째 캐시 버스팅이라는 의미로 읽힌다. 즉 오늘 이미 한 번 a로 올렸는데, 그게 충분하지 않았거나 추가 수정이 있었던 상황.

이런 수동 버전 관리의 트레이드오프

지금 구조는 수동 bumping이다. 이 방식이 나쁜 건 아닌데, 운영 중에 "왜 스타일이 안 바뀌지?" 이슈가 반복적으로 터지면 결국 해시 기반 자동화로 가야 한다는 신호로 읽어야 한다. 같은 날 a → b로 올린 것 자체가 그 반복의 흔적이다.

Astro 같은 정적 사이트 프레임워크는 빌드 타임에 asset fingerprinting을 지원하는 경우가 많은데, Base.astro에서 직접 하드코딩된 URL을 관리하고 있다면 그 기능을 아직 쓰지 않고 있거나 의도적으로 우회하고 있는 것이다. 프로젝트 규모나 배포 빈도에 따라 "지금은 수동이 더 빠르다"는 판단 자체는 충분히 합리적이다. 중요한 건 그 판단을 팀이 공유하고 있느냐다.

팀 관점에서 이 커밋이 갖는 의미

겉으로는 한 글자 수정이지만, 이 커밋이 올라오는 맥락을 팀 리드 입장에서 보면 몇 가지 체크 포인트가 생긴다.

• 배포 프로세스에 이 스텝이 명시적으로 있는가? 스타일 변경 → 캐시 키 bump가 체크리스트 항목이 아니면 누군가는 반드시 잊는다.
• 같은 날 두 번 bumping이 발생한 이유가 뭔가? 핫픽스였는지, 첫 번째 배포에서 뭔가 빠진 건지. 후자라면 배포 전 검증 단계에서 막았어야 하는 상황이다.
• 이 작업을 자동화할 타이밍이 왔는가? 빈도가 낮으면 수동 유지, 잦아지면 빌드 단계에 asset hash 도입을 검토하는 게 맞다.

작은 fix 커밋 하나도 "왜 지금 이게 필요했냐"를 팀 전체가 이해하는 구조를 만드는 게 결국 품질의 기반이 된다고 생각한다. 다음에 비슷한 상황이 오면 수동이냐 자동화냐 결정을 좀 더 의식적으로 해보고 싶다.

끝.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.