바로 답부터 말하면, Cloudflare Workers에서 정적 자산을 운영할 때는 “모든 파일을 오래 캐시”가 아니라 HTML·데이터 응답은 짧게, 해시가 붙은 CSS·JS·이미지는 길게, Workers 함수 응답은 의도한 헤더가 실제로 내려오는지 따로 확인하는 방식이 안전합니다. 이 글은 정적 자산 캐시 정책표를 기준으로 작은 회사 웹사이트나 랜딩 페이지를 배포하기 전에 확인할 순서를 정리한 실무용 초안입니다.
요약: 1) 정적 자산 폴더와 라우트를 먼저 고정하고, 2) 파일 종류별 캐시 시간을 나누고, 3) 배포 후 브라우저 개발자 도구와 curl로 Cache-Control 값을 확인하며, 4) Cloudflare 화면, 요금, Workers 기능 이름은 수시로 바뀔 수 있으므로 공식 문서와 대시보드의 최신 표시를 마지막에 다시 확인하세요.
1. 먼저 결정할 것: 정적 자산과 함수 응답을 분리합니다
Workers 프로젝트는 단순 파일 호스팅처럼 보이지만 실제 운영에서는 정적 자산, 라우트, 함수 로직이 한 주소 안에서 함께 움직입니다. 그래서 캐시 헤더를 정하기 전에 파일을 어디에 둘지, 어떤 경로가 정적 파일로 처리되는지, 어떤 경로가 Worker 코드로 처리되는지를 먼저 나눠야 합니다. 예를 들어 /assets/app.8f3a.css와 /api/status는 같은 도메인 아래 있어도 캐시 정책이 완전히 달라야 합니다. 정적 자산은 재사용성을 높이는 것이 목적이고, 함수 응답은 최신 상태와 오류 복구가 목적입니다. 이 기준을 문서 첫 줄에 적어두면 배포 담당자가 바뀌어도 헤더를 임의로 섞지 않습니다. 특히 운영자가 개발자 한 명뿐인 작은 팀에서는 이 구분을 안 해두면 나중에 화면 반영 지연, 이미지 교체 실패, API 응답 혼동이 모두 같은 문제처럼 보입니다.
2. 파일명에 해시가 있으면 긴 캐시가 유리합니다
빌드 도구가 app.8f3a2.js처럼 내용 해시가 붙은 파일명을 만들면 파일 내용이 바뀔 때 주소도 같이 바뀝니다. 이런 파일은 브라우저와 CDN에 오래 저장해도 새 버전 배포 시 충돌이 적습니다. 반대로 index.html, manifest.json, robots.txt처럼 고정 이름인 파일은 사용자가 오래된 진입 파일을 볼 수 있으므로 짧은 캐시나 재검증 정책이 더 안전합니다. 핵심은 확실히 버전이 바뀌는 파일만 길게 두는 것입니다. 배포 노트에는 긴 캐시 대상의 조건을 파일 확장자가 아니라 파일명 변경 여부로 적는 편이 좋습니다. 그래야 이미지, 폰트, 스크립트가 추가되어도 같은 판단을 유지할 수 있습니다.
3. 라우트 매칭을 먼저 확인해야 헤더 검수가 맞습니다
Cloudflare Workers는 라우트 설정에 따라 같은 프로젝트라도 특정 경로만 처리하거나 전체 도메인을 처리할 수 있습니다. 캐시 헤더가 맞지 않는다고 느낄 때 실제 원인은 헤더 코드가 아니라 라우트가 예상과 다르게 연결된 경우가 많습니다. 배포 전에는 대시보드에서 적용 도메인, 패턴, 환경 이름을 확인하고, 배포 후에는 대표 경로 세 개 이상을 열어 어떤 응답이 내려오는지 확인합니다. /, /assets/…, /api/…처럼 성격이 다른 주소를 나눠 확인하면 실수를 빨리 발견할 수 있습니다. 또한 미리보기 환경과 운영 환경의 라우트가 다르면 테스트에서 통과한 헤더가 실제 도메인에서는 보이지 않을 수 있으므로 환경 이름도 함께 기록해야 합니다.
4. 권장 캐시 정책표
아래 표는 시작점입니다. 브랜드 이미지처럼 자주 바뀌는 파일은 짧게 두고, 버전이 붙은 폰트나 아이콘은 길게 둘 수 있습니다. 중요한 것은 표를 팀 내부 배포 체크리스트에 붙여 같은 판단을 반복하는 것입니다. 표의 목적은 정답을 고정하는 것이 아니라 파일 종류별 질문을 빠뜨리지 않는 것입니다. 새 도구를 붙이거나 프레임워크를 바꿔도 HTML, 해시 자산, 이미지, 공개 데이터 응답을 따로 보는 습관은 그대로 유지됩니다.
| 대상 | 권장 방향 | 확인 포인트 |
|---|---|---|
| HTML 진입 파일 | 짧게 저장하거나 재검증 | 새 배포 후 제목·번들 경로가 즉시 바뀌는지 확인 |
| 해시가 붙은 CSS/JS | 길게 저장 | 파일명 변경 규칙이 빌드마다 유지되는지 확인 |
| 이미지·폰트 | 변경 빈도에 따라 중간 또는 길게 | 교체 가능성이 높은 로고는 별도 경로로 관리 |
| API 응답 | 업무 성격별로 별도 결정 | 개인화 응답과 공개 응답을 섞지 않기 |
5. 배포 전 체크리스트
배포 전에는 정적 자산 폴더 이름과 빌드 출력 경로를 먼저 문서화합니다. HTML, CSS, JS, 이미지, API 응답을 같은 캐시 값으로 묶지 않았는지 확인합니다. 라우트 패턴이 실제 도메인과 하위 경로를 덮는지 보고, 테스트 환경과 운영 환경의 프로젝트 이름을 구분합니다. 브라우저 강력 새로고침만 믿지 말고 네트워크 패널에서 실제 응답 헤더를 확인합니다. Cloudflare 대시보드의 메뉴명, 요금제별 제공 기능, Workers 세부 기능은 변경될 수 있으므로 마지막에 공식 화면을 다시 대조합니다. 이 단계에서 화면 캡처나 배포 로그 링크를 남기면 다음 담당자가 원인을 추적하기 쉽습니다.
- 정적 자산 폴더 이름과 빌드 출력 경로를 문서화했습니다.
- HTML, CSS, JS, 이미지, API 응답을 같은 캐시 값으로 묶지 않았습니다.
- 라우트 패턴이 실제 도메인과 하위 경로를 덮는지 확인했습니다.
- 브라우저 네트워크 패널에서 실제 응답 헤더를 확인했습니다.
- 공식 문서와 현재 대시보드 화면을 마지막에 대조했습니다.
6. curl로 보는 빠른 검수 방법
브라우저만 보면 캐시된 결과와 새 응답을 혼동할 수 있습니다. 운영자는 터미널에서 curl -I https://example.com/처럼 헤더만 확인하는 습관을 들이면 좋습니다. HTML 주소, 해시가 붙은 JS 주소, 이미지 주소를 각각 요청하고 Cache-Control, ETag, Last-Modified 같은 값을 기록합니다. 값이 비어 있다면 기본 동작에 기대고 있다는 뜻일 수 있으므로 프로젝트 의도와 맞는지 다시 봅니다. 여러 명이 운영하는 팀이라면 검수 결과를 배포 노트에 붙여 이번 배포에서 어떤 파일을 얼마나 캐시했는지 남겨두는 편이 안전합니다. 반복 배포가 많다면 이 명령을 간단한 스모크 체크로 만들어 실패 시 알림을 주는 것도 좋습니다.
7. 자주 나는 실수와 해결 순서
첫 번째 실수는 HTML까지 너무 오래 저장해 새 배포가 늦게 보이는 상황입니다. 이때 사용자는 사이트가 업데이트되지 않았다고 느낍니다. 두 번째 실수는 이미지 파일을 같은 이름으로 덮어쓰면서 캐시가 남는 상황입니다. 세 번째 실수는 함수 응답에 정적 파일용 헤더를 그대로 붙이는 것입니다. 해결 순서는 간단합니다. 먼저 문제가 생긴 URL을 하나로 고정하고, 실제 헤더를 확인하고, 라우트가 맞는지 보고, 마지막으로 파일명 버전 전략을 점검합니다. 이 순서가 있어야 대시보드 설정을 이것저것 바꾸며 원인을 잃어버리지 않습니다. 운영 중 급한 수정이 필요해도 원인을 남기지 않으면 다음 배포에서 같은 문제가 되풀이됩니다.
8. 작은 팀용 운영 문서 작성법
캐시 정책은 개발자만 보는 설정으로 끝내기보다 운영 문서에 짧게 남기는 것이 좋습니다. 문서에는 긴 캐시 대상, 짧은 캐시 대상, 배포 후 확인할 URL, 문제가 생기면 되돌릴 순서 네 항목만 있어도 충분합니다. 마케팅 랜딩 페이지, 도움말 문서, 다운로드 페이지처럼 비개발자가 확인하는 화면은 새 문구가 바로 보이는지 중요합니다. 따라서 배포 담당자는 파일별 캐시 시간보다 사용자가 보는 변경 지점을 먼저 생각해야 합니다. 이 관점이 있으면 속도와 최신성 사이에서 균형을 잡기 쉽습니다. 문서는 길 필요가 없고, 배포 전에 체크박스로 훑을 수 있어야 실제로 쓰입니다.
9. 최신 기능과 화면 변경 고지
Cloudflare Workers, Static Assets, Routes 관련 화면과 용어는 제품 업데이트에 따라 바뀔 수 있습니다. 또한 요금제별 제공 기능, 베타 표시, 메뉴 위치, 배포 로그 표현도 변경될 수 있습니다. 이 글의 순서는 실무 점검 흐름을 설명하는 참고 자료이며, 실제 적용 전에는 Cloudflare 공식 문서와 현재 계정 대시보드의 최신 화면을 반드시 함께 확인해야 합니다. 특히 운영 도메인에 적용하기 전에는 테스트 하위 도메인이나 미리보기 환경에서 먼저 확인하는 편이 좋습니다. 새 기능이 보이지 않는다면 계정 권한, 프로젝트 유형, 배포 도구 버전도 같이 확인해야 합니다.
10. 바로 적용할 15분 점검 루틴
첫 5분은 파일 목록을 봅니다. 해시가 붙은 자산과 고정 이름 파일을 나눕니다. 다음 5분은 라우트와 배포 환경을 확인합니다. 마지막 5분은 curl -I 또는 브라우저 네트워크 패널로 대표 URL의 헤더를 기록합니다. 이 정도만 해도 왜 바뀐 화면이 안 보이지, 이미지가 예전 것처럼 남아 있지 같은 반복 문의를 줄일 수 있습니다. 자동화가 필요하다면 나중에 배포 스크립트에 헤더 확인 명령을 넣고, 실패하면 배포 노트에 경고를 남기는 방식으로 확장하면 됩니다. 처음부터 완벽한 플랫폼을 만들기보다 작은 검수 루틴을 꾸준히 실행하는 것이 더 현실적입니다.
FAQ
Q1. 모든 정적 파일에 같은 Cache-Control을 넣어도 되나요?
권장하지 않습니다. 파일명이 바뀌는 자산과 고정 이름 진입 파일은 갱신 방식이 다르기 때문에 최소한 HTML과 해시 자산은 분리하는 편이 안전합니다.
Q2. Cloudflare 대시보드에서만 확인하면 충분한가요?
아닙니다. 대시보드 설정은 의도를 보여주지만 사용자가 받는 실제 응답은 네트워크 요청으로 확인해야 합니다. 배포 후 대표 URL의 응답 헤더를 따로 보세요.
Q3. 캐시를 길게 두면 무조건 사이트가 빨라지나요?
반드시 그렇지는 않습니다. 자주 바뀌는 HTML이나 설정 파일까지 길게 두면 최신 화면 반영이 늦어질 수 있습니다. 오래 저장할 대상만 골라야 합니다.
Q4. 작은 랜딩 페이지도 이런 표가 필요한가요?
필요합니다. 페이지가 작을수록 한 번의 캐시 실수가 전체 화면에 바로 드러납니다. 표는 거창한 문서가 아니라 배포 전 확인 항목을 맞추는 장치입니다.
Q5. Workers 기능 이름이 문서와 다르면 어떻게 하나요?
제품 화면은 계속 바뀔 수 있습니다. 공식 문서의 현재 페이지, 계정 대시보드의 실제 메뉴, 배포 로그를 함께 확인하고 이 글의 순서는 체크 흐름으로만 활용하세요.
