style.css?v=123의 정체? 개발자가 알아야 할 “캐시버스팅”

들어가며

웹사이트를 개발하다 보면 정말 이상한 상황을 한 번쯤 경험하게 됩니다.

분명히 style.css를 수정했습니다. 서버에 정상적으로 배포했고 파일을 직접 열어봐도 변경된 내용이 들어 있습니다.

그런데 내 컴퓨터에서는 예전 화면이 그대로 보입니다.

JavaScript도 마찬가지입니다. 코드를 수정하고 배포했는데 브라우저에서는 이전 JavaScript가 실행되는 것처럼 보입니다. 개발자 도구에서 파일을 확인해보면 도대체 어디서 이전 파일을 가져오는 건지 헷갈리기도 합니다.

이런 상황에서 자주 사용되는 방법이 바로 정적 파일 캐시버스팅(Cache Busting)입니다.

이름만 들으면 상당히 복잡해 보이지만 원리는 생각보다 간단합니다.

브라우저가 예전 파일을 계속 사용하지 않도록, 파일의 URL을 변경해 새로운 파일이라고 인식시키는 방법입니다.

왜 CSS와 JavaScript가 바로 변경되지 않을까?

브라우저는 웹사이트를 빠르게 보여주기 위해 여러 리소스를 캐시할 수 있습니다.

HTML을 열었을 때 style.css와 app.js를 다운로드했다고 생각해보겠습니다.

사용자가 다음에 같은 페이지를 다시 방문했을 때 매번 CSS와 JavaScript를 서버에서 새로 다운로드한다면 불필요한 네트워크 요청이 계속 발생합니다.

그래서 브라우저는 이전에 받아둔 파일을 재사용할 수 있습니다.

이것 자체는 나쁜 기능이 아닙니다.

오히려 웹사이트의 로딩 속도를 빠르게 만들어주는 중요한 기능입니다.

문제는 파일 내용이 변경됐는데 브라우저가 기존 캐시를 계속 사용하는 경우입니다.

개발자 입장에서는 분명 새 버전을 배포했는데 사용자는 이전 CSS나 JavaScript를 보고 있는 상황이 발생할 수 있습니다.

특히 배포 직후 이런 문제가 발생하면 “서버에는 분명 새 파일이 있는데 왜 화면이 안 바뀌지?”라는 상황이 생깁니다.

가장 간단한 캐시버스팅 방법

가장 쉽게 사용할 수 있는 방법은 정적 파일 URL 뒤에 버전 값을 붙이는 것입니다.

예를 들어 기존 HTML이 다음과 같다고 해보겠습니다.

<link rel="stylesheet" href="/css/style.css">
<script src="/js/app.js"></script>

여기에 버전 값을 추가합니다.

<link rel="stylesheet" href="/css/style.css?v=1.0.1">
<script src="/js/app.js?v=1.0.1"></script>

파일 이름은 똑같이 style.css이지만 브라우저 입장에서는 URL이 달라졌습니다.

기존 URL은 다음과 같습니다.

/css/style.css

변경된 URL은 다음과 같습니다.

/css/style.css?v=1.0.1

브라우저는 서로 다른 URL로 인식할 수 있기 때문에 새로운 파일을 요청하게 됩니다.

이것이 가장 단순한 형태의 정적 파일 캐시버스팅입니다.

파일 이름을 바꾸는 방법도 있다

URL 뒤에 쿼리스트링을 붙이는 것 외에도 파일 이름 자체에 버전을 포함시키는 방법이 있습니다.

예를 들어 다음과 같이 사용할 수 있습니다.

style.css

파일을 수정한 뒤에는

style.v2.css

또는

style.20260909.css

처럼 변경하는 방식입니다.

이 방법 역시 브라우저 입장에서는 새로운 URL이기 때문에 기존에 캐시된 파일과 구분할 수 있습니다.

다만 실제 프로젝트에서는 파일 이름을 계속 변경하는 것보다 ?v= 같은 버전 파라미터를 사용하는 경우가 편리할 수 있습니다.

실무에서는 날짜나 버전을 많이 사용한다

개발 과정에서는 간단하게 다음처럼 사용할 수 있습니다.

<script src="/js/app.js?v=20260909"></script>

CSS도 마찬가지입니다.

<link rel="stylesheet" href="/css/style.css?v=20260909">

파일을 수정하고 배포할 때 버전 값을 변경하는 것입니다.

그러면 브라우저는 새로운 URL을 요청하게 되고 최신 파일을 가져올 가능성이 높아집니다.

하지만 여기서 중요한 것은 캐시버스팅의 목적이 캐시를 무조건 없애는 것이 아니라는 점입니다.

캐시는 그대로 활용하면서 파일이 변경된 경우에만 새로운 URL을 사용하는 것이 핵심입니다.

더 좋은 방법은 파일 내용으로 버전을 만드는 것

대규모 프로젝트에서는 단순히 v=1, v=2처럼 개발자가 직접 버전 번호를 관리하는 것보다 파일 내용이 변경될 때 파일명도 자동으로 변경하는 방식을 많이 사용합니다.

예를 들어 원래 파일이

app.js

였다면 빌드 과정에서

app.a83f21.js

처럼 만들어질 수 있습니다.

파일 내용이 변경되면 해시 값도 달라져서

app.91c7de.js

와 같이 새로운 파일이 만들어집니다.

이런 방식을 Content Hash, 또는 파일명 해시 기반 캐시버스팅이라고 부릅니다.

이 방법의 장점은 파일 내용이 실제로 변경됐을 때만 URL이 달라진다는 것입니다.

내용이 그대로라면 같은 파일명을 계속 사용할 수 있기 때문에 브라우저 캐시의 장점을 제대로 활용할 수 있습니다.

캐시를 오래 유지하면서도 최신 파일을 받을 수 있다

여기서 캐시버스팅의 진짜 장점이 나타납니다.

웹 서버에서 CSS나 JavaScript 파일을 오랫동안 캐시하도록 설정했다고 가정해보겠습니다.

일반적으로 캐시 기간을 길게 설정하면 성능에는 유리하지만 파일을 수정했을 때 사용자가 오래된 파일을 볼 가능성이 있습니다.

그런데 파일 URL에 버전이나 해시를 적용하면 상황이 달라집니다.

파일이 변경되면 새로운 URL이 만들어집니다.

브라우저 입장에서는 완전히 다른 리소스이기 때문에 새로운 파일을 다운로드합니다.

반대로 파일이 변경되지 않았다면 기존 URL을 그대로 사용할 수 있습니다.

즉, 캐시를 적극적으로 사용하면서 배포된 변경 사항도 안정적으로 전달할 수 있는 구조를 만들 수 있습니다.

JSP나 서버 사이드 페이지에서도 활용할 수 있다

Java 기반 웹 애플리케이션이나 JSP를 사용하는 프로젝트라면 정적 파일의 버전 값을 동적으로 관리하는 방법도 생각해볼 수 있습니다.

예를 들어 JSP에서 다음과 같은 형태로 CSS를 연결할 수 있습니다.

<link rel="stylesheet"
      href="${pageContext.request.contextPath}/css/style.css?v=20260909">

JavaScript도 같은 방식으로 처리할 수 있습니다.

<script src="${pageContext.request.contextPath}/js/app.js?v=20260909"></script>

물론 실제 운영 환경에서는 버전 값을 코드에 직접 반복해서 작성하기보다는 애플리케이션 버전이나 빌드 번호를 이용해 자동으로 관리하는 것이 더 편리합니다.

캐시를 무조건 끄는 것은 좋은 해결책일까?

개발하다 보면 캐시 문제가 귀찮아서 브라우저 캐시를 아예 사용하지 않도록 설정하고 싶을 때가 있습니다.

하지만 운영 환경에서는 이것이 반드시 좋은 방법은 아닙니다.

CSS와 JavaScript를 매번 새로 다운로드하게 만들면 사용자의 네트워크 요청이 늘어나고 페이지 로딩에도 영향을 줄 수 있습니다.

특히 이미지, JavaScript, CSS처럼 용량이 큰 정적 파일은 캐시를 적절하게 활용하는 것이 중요합니다.

그래서 운영 환경에서는 캐시를 끄는 것보다 캐시를 제대로 활용하면서 변경된 파일만 새롭게 가져오도록 만드는 것이 더 좋은 접근입니다.

캐시버스팅과 CDN을 함께 사용한다면?

요즘 웹사이트에서는 CDN(Content Delivery Network)을 사용하는 경우도 많습니다.

이때도 캐시버스팅은 상당히 중요합니다.

CDN 역시 정적 파일을 캐시하기 때문에 서버의 파일을 수정했다고 해서 전 세계 CDN에 저장된 기존 파일이 즉시 새로운 파일로 바뀌는 것은 아닐 수 있습니다.

이때 파일 URL에 버전이나 콘텐츠 해시를 적용하면 새로운 URL로 요청할 수 있습니다.

예를 들어 기존 파일이

/js/app.js?v=1

이었다면 새로운 배포에서는

/js/app.js?v=2

로 변경합니다.

CDN 입장에서도 새로운 URL이기 때문에 새로운 리소스로 처리할 수 있습니다.

개발할 때 기억하면 좋은 한 가지

CSS나 JavaScript를 수정했는데 화면이 바뀌지 않는다면 무조건 코드부터 의심할 필요는 없습니다.

먼저 다음 부분을 확인해보는 것이 좋습니다.

브라우저 캐시 → CDN 캐시 → 서버 캐시 → 실제 정적 파일

이 순서로 확인하다 보면 의외로 캐시 때문에 발생한 문제를 쉽게 찾을 수 있습니다.

특히 개발자 도구의 Network 탭에서 실제로 어떤 파일을 받고 있는지 확인하면 도움이 됩니다.

파일의 요청 URL과 응답 내용을 직접 확인하면 브라우저가 오래된 파일을 사용하고 있는지 판단하기가 훨씬 쉬워집니다.

마무리

정적 파일 캐시버스팅은 웹 개발에서 상당히 단순하면서도 실무에서 자주 사용되는 방법입니다.

핵심은 어렵지 않습니다.

브라우저가 style.css라는 동일한 URL을 계속 사용하면 이전에 저장된 캐시를 사용할 수 있습니다.

그래서 파일이 변경됐을 때 URL을

style.css?v=2

처럼 변경하거나,

style.a83f21.css

처럼 파일 이름에 콘텐츠 해시를 포함시키는 것입니다.

결국 중요한 것은 캐시를 없애는 것이 아닙니다.

캐시의 성능상 이점은 그대로 가져가면서, 새로운 파일이 배포됐다는 사실을 브라우저와 CDN에 알려주는 것이 캐시버스팅의 핵심입니다.

작은 JSP 프로젝트라면 ?v=날짜 방식부터 시작해도 충분합니다.

프로젝트 규모가 커지고 빌드 자동화가 필요해진다면 콘텐츠 해시 방식까지 고려해보면 좋습니다.

웹사이트를 운영하면서 “분명 수정했는데 사용자 화면에는 이전 화면이 나온다”라는 문제가 발생했다면, 그때는 코드만 계속 수정하기보다는 정적 파일 캐시와 캐시버스팅부터 확인해보는 것을 추천합니다.