클라우드플레어 Pages 빌드 캐시 최적화, 맨날 5분 걸리던 배포 30초 컷 낸 썰 ⚡

글 오타 하나 고치고 푸시했는데 빌드 도는 것만 5분 넘게 멍때려본 사람 손들어보세요. 진짜 저처럼 복장 터지던 개발자들에게 클라우드플레어 Pages 빌드 캐시 설정은 구원을 넘어 인생의 치트키 수준입니다.

매번 깃허브 푸시할 때마다 수백 메가짜리 의존성 패키지를 처음부터 다운로드하는 꼴을 지켜보고 있으면 모니터를 부수고 싶어집니다.

하지만 이거 딱 3초 투자해서 켜놓기만 해도 5분 걸리던 배포 시간이 거짓말처럼 30초대로 수직 낙하합니다.

클라우드플레어 Pages 빌드 시간 단축, 배포할 때마다 5분씩 멍때리던 이유

Cloudflare Pages의 기본 빌드 파이프라인은 캐시가 꺼져 있으면 매 배포마다 완전히 깨끗한 가상 컨테이너에서 의존성 설치와 에셋 번들링을 처음부터 다시 수행합니다.

코드에서 텍스트 한 줄 바꿨을 뿐인데 npm install 돌리면서 패키지 1000개를 새로 긁어오는 광경을 보고 있으면 현타가 제대로 옵니다.

특히 정적 웹사이트 클라우드플레어 페이지 배포 방법 가이드를 보고 기본값으로 세팅해 둔 분들은 '원래 무료 서비스니까 느린가 보다' 하고 그냥 체념하기 일쑤입니다.

하지만 무료 플랜도 매월 제공되는 빌드 시간 한도가 정해져 있어서, 이렇게 무의미하게 허비되는 빌드 시간 때문에 한 달 쿼터가 줄줄 새어나갑니다.

"글자 하나 고치고 5분 기다리는 건 진짜 인간적으로 너무한 거 아니냐고 ㅋㅋㅋ"

Cloudflare Pages Build Cache 설정 활성화, 클릭 한 번으로 배포 속도 폭발시키는 법

Cloudflare 대시보드의 Workers & Pages 프로젝트 설정에서 Build cache 항목을 Enable로 전환하면 패키지 매니저 글로벌 캐시와 프레임워크 중간 산출물이 배포 간에 자동 유지됩니다.

적용 방법도 너무 단순해서 허탈할 지경입니다.

Cloudflare 대시보드에 로그인한 뒤 본인의 Pages 프로젝트를 선택하고 Settings > Build > Build cache 메뉴로 이동합니다.

거기서 토글을 Enable로 켜주기만 하면 세팅이 끝납니다.

이제 다음 배포를 트리거하면 빌드 로그 상단에 Restoring build cache... 라는 영롱한 메시지가 뜨면서 기적이 시작됩니다.

무겁기로 소문난 Next.js나 Astro 프로젝트조차도 이전 빌드 산출물을 그대로 재활용하기 때문에 빌드 시간이 70%에서 최대 90%까지 시원하게 깎여나갑니다.

node_modules 빌드 캐싱 트릭, 지원 디렉터리 경로 모르면 헛고생하는 이유

Cloudflare Pages 빌드 캐시는 시스템에 등록된 화이트리스트(Allow-list) 디렉터리만 보존하므로 커스텀 캐시 산출물은 시스템이 감시하는 지정 폴더 경로로 리다이렉트해야 합니다.

아무 폴더나 대충 캐시해 주겠거니 믿었다가는 빌드가 끝나자마자 다음 턴에 모조리 증발해 버리는 마법을 보게 됩니다.

클라우드플레어가 공식적으로 추적하고 저장해 주는 경로는 npm(.npm), yarn(.cache/yarn), pnpm(.pnpm-store), bun(.bun/install/cache) 등 패키지 매니저의 글로벌 캐시 디렉터리입니다.

여기에 Next.js(.next/cache)나 Astro(node_modules/.astro) 같은 주요 프레임워크의 빌드 캐시 경로도 자동으로 포함됩니다.

만약 여러분이 Hugo나 커스텀 파이썬 SSG 스크립트를 돌린다면 hugo --minify --cacheDir=$PWD/.cache처럼 캐시 저장 위치를 클라우드플레어가 감시하는 경로로 콕 집어 명시해야 캐시 혜택을 온전히 누릴 수 있습니다.

요즘 각광받는 2026년 정적 사이트 생성기(SSG) 트렌드 흐름에 맞춰 초경량 파이프라인을 구축할 때도 이 캐시 디렉터리 경로 지정 하나가 배포 효율의 9할을 좌우합니다.

Pages 배포 실패 시 Clear build cache 초기화, 가끔 캐시 꼬였을 때 한 방 해결법

의존성 패키지 버전 불일치나 손상된 중간 산출물로 인해 원인을 알 수 없는 빌드 오류가 반복될 때는 대시보드에서 Clear build cache를 실행해 클린 빌드로 복구해야 합니다.

빌드 캐시가 만능 치트키인 건 맞지만, 라이브러리를 대규모로 업그레이드하거나 메이저 버전을 올릴 때 가끔 이전 캐시 찌꺼기와 충돌하며 빌드가 터지는 순간이 찾아옵니다.

로컬 환경에서는 아무 문제 없이 쌩쌩 잘 돌아가는데 클라우드플레어 서버만 올라가면 시뻘건 에러를 뿜으며 사망 선고를 내리는 경우가 딱 이 상황입니다.

"로컬에선 1초 만에 빌드되는데 Pages만 올라가면 터지는 귀신 들린 현상 경험해 봄?"

이럴 때는 멘붕 와서 코드 갈아엎지 마시고, 아까 들어갔던 Settings > Build > Build cache 메뉴에서 Clear build cache 버튼을 누르고 다시 배포를 돌리면 말끔하게 해결됩니다.

더러워진 캐시를 한 번 싹 비워내고 새로 깨끗한 캐시를 적재하므로, 원인 모를 배포 실패를 단칼에 해결할 수 있습니다.

자주 묻는 질문 (FAQ)

Q. 클라우드플레어 Pages 빌드 캐시는 무료 요금제에서도 제한 없이 사용 가능한가요?

네. Cloudflare Pages 빌드 캐시 기능은 무료 플랜을 포함한 모든 사용자에게 기본 제공되며 추가 비용이 전혀 들지 않습니다. 활성화하는 즉시 배포 빌드 시간을 대폭 줄여 무료 플랜의 월간 빌드 시간 한도를 아끼는 데 큰 도움이 됩니다.

Q. 빌드 캐시를 활성화했는데도 배포 속도에 변화가 없는 이유는 무엇인가요?

캐시 허용 목록(Allow-list) 외부에 생성된 임시 파일이거나 package.json 변경으로 전체 패키지가 재설치되었기 때문입니다. 배포 상세 로그에서 Restoring build cache 메시지가 정상적으로 출력되었는지 먼저 확인해 보시기 바랍니다.

Q. 캐시 오염으로 인해 빌드가 실패할 때 강제로 초기화하는 방법은 무엇인가요?

Cloudflare 대시보드의 'Settings > Build > Build cache' 섹션에서 'Clear build cache' 버튼을 클릭하면 됩니다. 기존 저장된 캐시가 즉시 삭제되며 다음 배포 시 완전히 새로운 클린 빌드가 실행됩니다.

맨날 배포 버튼 누르고 커피 한 잔 뽑아오던 답답한 시절은 이제 끝났습니다.

아직도 5분씩 모니터만 바라보며 속 태우셨다면, 지금 당장 대시보드 들어가서 딱 3초 만에 켜보시길 권장합니다.

여러분의 클라우드플레어 Pages 빌드 캐시 최적화 전후 배포 속도는 몇 초나 줄어드셨나요? 실전에서 겪으신 체감 속도나 숨겨진 꿀팁이 있다면 댓글로 자유롭게 공유해 주세요!