React 앱 번들 캐시 전략과 해시 관리

개요

페이지가 갱신되지 않거나 오래된 자원이 남아 사용자 경험이 저하되는 문제는 대부분 캐시 정책과 해시 관리에서 비롯된다. 이 글은 React 앱에서 번들 캐시 전략과 정적 자원 해시 관리 방법을 단계적으로 설명한다. 개념부터 구현 예시, 서버 설정과 배포 파이프라인 적용까지 실무에서 자주 마주치는 상황을 중심으로 정리한다.

번들 캐시가 중요한 이유

사용자 경험과 비용

브라우저 캐시는 페이지 로딩 속도를 높이고 서버 비용을 줄인다. 그러나 캐시된 파일이 오래 유지되면 최신 코드가 반영되지 않는다. 따라서 캐시의 장점을 살리면서 업데이트가 필요할 때만 클라이언트가 새 파일을 내려받게 만드는 전략이 필요하다.

기본 원리

핵심은 파일 이름에 콘텐츠 기반 해시를 포함시키는 것이다. 파일 내용이 바뀌면 해시가 바뀌고, 브라우저는 새 파일을 요청한다. 반대로 내용이 같다면 동일한 해시를 유지해 캐시의 이점을 누릴 수 있다.

해시 전략의 종류

hash, chunkhash, contenthash 비교

• hash: 전체 빌드 결과를 기반으로 한 해시. 빌드가 달라지면 모든 파일 해시가 변한다.
• chunkhash: 청크 단위 해시. 여러 entry 포인트가 있을 때 유용하지만 일부 도구에서 한계가 있다.
• contenthash: 파일 내용 자체를 기반으로 하는 해시로, 가장 세분화된 캐시 무효화가 가능하다.

React 앱에서는 contenthash를 권장한다. 변경된 파일만 새 이름을 받으므로 캐시 미스 범위를 최소화할 수 있다.

Webpack 설정 예시

아래는 출력 파일 이름에 contenthash를 적용한 간단한 예시이다.

module.exports = {
  output: {
    filename: 'static/js/[name].[contenthash:8].js',
    chunkFilename: 'static/js/[name].[contenthash:8].chunk.js',
    path: __dirname + '/build',
    publicPath: '/',
  },
};

React 프로젝트에서의 적용

Create React App(CRA)와 해시

CRA는 기본적으로 빌드 산출물에 contenthash를 사용한다. eject하지 않고도 대부분의 경우 별도 설정 없이 캐시 무효화가 동작한다. 커스텀 설정이 필요한 경우 webpack 설정을 조정하거나 빌드 출력물을 다루는 플러그인을 활용한다.

서비스 워커와 캐시 전략

오프라인 기능이나 자원 프리캐싱을 위해 서비스 워커를 사용하는 경우, 캐시 네임에 빌드 해시를 포함해 안정성을 높일 수 있다. 예를 들어 캐시 네임을 'app-cache-<빌드해시>' 형태로 사용하면 배포 시 자동으로 새 캐시를 생성한다.

const CACHE_NAME = 'app-cache-' + process.env.BUILD_HASH;
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(['/index.html', '/static/js/main.js']))
  );
});

서버 측 캐시 제어

Cache-Control 헤더 설계

정적 자원에는 긴 만료 시간을 주고(예: max-age=31536000), HTML은 짧게 설정한다. 이렇게 하면 해시로 이름이 바뀐 파일만 새로 받아오고, index.html처럼 참조를 업데이트하는 파일은 자주 갱신되도록 한다.

Nginx 예시

location /static/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}
location / {
  try_files $uri /index.html;
  add_header Cache-Control "no-cache";
}

배포 파이프라인에서의 해시 활용

CI/CD 단계에서 빌드 해시를 환경 변수로 남기면, 서비스 워커, 메타데이터, 모니터링 태그 등에 동일한 값을 주입할 수 있다. 또한 이전 배포의 오래된 캐시를 정리하는 스크립트를 포함하면 용량 누수를 방지할 수 있다.

• 빌드: contenthash 포함 출력 생성
• 아티팩트 업로드: 파일명 기준으로 업로드 및 캐시 무효화
• 서비스 등록: 캐시 네임 및 메타데이터 업데이트
• 정리: 오래된 캐시 및 파일 제거

현실적인 고려사항

해시 전략은 장점이 많지만 구현 오류로 인해 캐시 무효화가 실패하면 사용자에게 오래된 코드가 전달된다. 아래 사항을 점검한다.

• HTML 템플릿에서 정적 자원의 경로가 빌드 산출물과 일치하는지 확인
• 서비스 워커가 업데이트 로직을 제대로 처리하는지 점검
• 서버 캐시 헤더가 잘못 설정되어 있지 않은지 검증

마무리

React 앱의 번들 캐시 전략은 contenthash 기반 파일명, 서비스 워커와의 연동, 서버의 Cache-Control 정책이 조화롭게 작동해야 효과를 발휘한다. 빌드 파이프라인에서 해시 값을 활용해 메타데이터와 캐시 네임을 일관되게 관리하면 배포 안정성이 크게 향상된다. 작은 설정 하나가 사용자 경험을 좌우하므로 배포 과정에서 해시와 캐시 정책을 반드시 확인할 것을 권장한다.