Cloudflare Pages 호스팅을 사용하면 프런트엔드 팀은 빠르고 안전하며 서버 관리가 필요 없는 코드를 배포할 수 있습니다. Cloudflare Pages 를 사용하면 개발자는 정적 웹 애플리케이션, 싱글 페이지 앱(SPA), 서버 사이드 렌더링(SSR) 프레임워크를 배포할 수 있는 고성능 에지 네이티브 플랫폼을 확보하게 됩니다. Git 저장소에 직접 연결함으로써 Cloudflare는 빌드 파이프라인을 자동화하고, 프리뷰 배포를 생성하며, 에셋을 전 세계에 호스팅합니다. 이 가이드에서는 Git을 연결하고, 빌드 설정을 구성하고, 사용자 지정 도메인을 설정하고, 리디렉션을 구성하는 방법을 설명합니다.

요약(TL;DR)

  • 에지 네이티브 프런트엔드 앱을 배포하세요. Cloudflare Pages는 Cloudflare 네트워크에서 에셋을 전 세계에 서빙하여 1초 미만의 로드 시간을 보장합니다.
  • Git 통합을 자동화하세요. 저장소를 연결하여 자동 빌드를 트리거하고 모든 커밋에 대해 프리뷰 URL을 생성하세요.
  • 프레임워크 빌드 설정을 구성하세요. React, Vue, Next.js, Hugo, Astro의 출력 디렉터리와 명령어를 설정하세요.
  • 공개 폴더 안에 일반 텍스트 _redirects 및 _headers 파일을 사용하여 리디렉션 및 헤더 규칙을 적용하세요.
  • Cloudflare가 관리하는 무료 자동 갱신 SSL 인증서로 사용자 지정 도메인을 매핑하세요.

Cloudflare Pages란 무엇인가?

Cloudflare Pages는 Netlify나 Vercel과 유사한 프런트엔드 개발자용 서버리스 호스팅 플랫폼으로, Cloudflare의 글로벌 인프라 위에 직접 구축되어 있습니다.

Cloudflare Pages는 파일을 단일 클라우드 서버에 호스팅하는 대신 여러분의 HTML, CSS, JavaScript, 이미지를 전 세계 에지 위치에 분산합니다. 사용자가 여러분의 사이트를 요청하면 가장 가까운 위치에서 에셋이 서빙되어 네트워크 지연 시간을 줄입니다. 서버 사이드 로직이 필요한 프로젝트의 경우, Pages는 Cloudflare Workers와 통합되어 백엔드 함수를 실행합니다. Pages를 다른 에지 컴퓨팅 서비스와 비교하려면 Cloudflare Pages vs Workers 가이드를 읽어보세요.

사전 준비 사항

시작하기 전에 다음 사항이 갖춰져 있는지 확인하세요.

  • 프로젝트가 포함된 GitHub 또는 GitLab의 Git 저장소(또는 직접 업로드할 준비가 된 빌드된 파일).
  • 정적 에셋을 출력하는 프레임워크 — React(Vite), Vue, Astro, SvelteKit, Hugo 또는 순수 HTML. 서버 렌더링 프레임워크도 Pages Functions를 통해 작동합니다.
  • 정상 작동하는 로컬 빌드. 무언가를 연결하기 전에 빌드 명령어(예: npm run build)를 실행하여 출력 폴더가 오류 없이 생성되는지 확인하세요.
  • 무료 Cloudflare 계정. 무료 요금제에는 신용카드가 필요하지 않습니다.
  • 로컬에 설치된 Node.js(권장). 이를 통해 빌드를 재현하고 Wrangler 명령줄 도구를 사용할 수 있습니다.

간단한 확인이 나중에 몇 시간의 디버깅을 절약해 줍니다. 여러분의 사이트가 자신의 컴퓨터에서 깔끔하게 빌드되지 않는다면 Cloudflare의 러너에서도 빌드되지 않습니다. 먼저 로컬 오류를 해결하세요.

1단계: Git 저장소 연결하기

시작하려면 Cloudflare 대시보드에 로그인하고 Compute > Pages로 이동한 다음 Create a project를 클릭하세요.

Connect to Git를 선택하여 GitHub 또는 GitLab 계정을 연결하세요. 정적 웹 애플리케이션이 포함된 저장소를 선택하세요. 이 통합은 지속적 통합(CI) 파이프라인을 구축하기 때문에 유용합니다. 프로덕션 브랜치에 코드를 푸시할 때마다 Cloudflare가 자동으로 업데이트를 빌드하고 배포합니다. 다른 커밋의 경우 Cloudflare가 고유한 “프리뷰 URL"을 생성하여 병합 전에 변경 사항을 테스트할 수 있습니다.

2단계: 빌드 설정 구성하기

Cloudflare Pages는 인기 있는 정적 사이트 생성기와 프런트엔드 프레임워크를 지원합니다. 설정 마법사에서 여러분의 스택에 따라 다음 설정을 구성하세요.

  • 빌드 명령어: package.json에 정의된 빌드 스크립트(예: npm run build 또는 hugo --minify).
  • 빌드 출력 디렉터리: 컴파일된 정적 파일이 포함된 폴더(예: dist, build 또는 public).
  • 환경 변수: 빌드 스크립트에 API 키나 구성 변수가 필요한 경우 여기에서 정의하세요.

Cloudflare는 많은 프레임워크를 자동 감지하지만, 프리셋을 확인하면 첫 빌드 실패를 방지할 수 있습니다. 일반적인 조합은 다음과 같습니다.

프레임워크빌드 명령어출력 디렉터리
React (Vite)npm run builddist
React (Create React App)npm run buildbuild
Next.js (static export)npx next buildout
Astronpm run builddist
Vue (Vite)npm run builddist
SvelteKitnpm run build.svelte-kit/cloudflare
Hugohugo --minifypublic

Node 버전을 고정하세요. “로컬에서는 작동하지만 Cloudflare에서는 실패한다"의 흔한 원인은 빌드 러너의 기본 Node 버전과 프로젝트가 기대하는 버전 간의 불일치입니다. 대시보드에서 환경 변수로 명시적으로 선언하거나:

1NODE_VERSION = 20

저장소 루트에 .node-version 파일을 커밋하여 선언하세요:

120

3단계: 리디렉션 및 헤더 설정하기

싱글 페이지 앱(React Router 등)이나 레거시 URL 마이그레이션의 경우 라우팅 및 리디렉션 규칙을 구성해야 합니다. Pages는 출력 디렉터리에 배치된 간단한 텍스트 파일을 통해 이를 처리합니다.

리디렉션 (_redirects)

공개 폴더에 _redirects라는 파일을 만드세요. React SPA가 클라이언트 사이드 라우팅을 깔끔하게 처리하려면 다음 폴백 규칙을 추가하세요:

1/*  /index.html  200

이는 모든 요청이 index.html로 해석되도록 강제하여 JavaScript 라우터가 경로를 관리할 수 있게 합니다.

순서가 중요합니다. Cloudflare는 규칙을 위에서 아래로 평가하고 첫 번째 일치에서 멈추므로, 구체적인 리디렉션은 포괄 폴백 위에 있어야 합니다:

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

:splat 자리 표시자는 경로에서 일치한 부분을 대상까지 전달합니다. 무료 요금제는 프로젝트당 최대 2,000개의 정적 리디렉션 규칙을 허용하며, 그 이상은 로직을 Pages Function이나 Bulk Redirects로 옮기세요.

사용자 지정 헤더 (_headers)

보안 규칙, Referrer-Policy 또는 사용자 지정 캐시 제어를 적용하려면 _headers라는 파일을 만드세요:

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

이 같은 파일은 캐싱을 조정하기에 적합한 곳입니다. 지문이 붙은 불변 에셋은 1년 동안 캐시할 수 있는 반면, HTML은 최신 상태로 유지되어 사용자가 항상 최신 빌드를 받게 됩니다:

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

이러한 규칙이 기존 백엔드 라우팅과 어떻게 비교되는지 보려면 Cloudflare Workers로 서버리스 API 구축하기 를 읽어보세요.

4단계: 사용자 지정 도메인 매핑하기

배포되면 Cloudflare는 기본 하위 도메인(예: your-project.pages.dev)을 제공합니다.

사용자 지정 도메인을 매핑하려면 Pages 프로젝트의 Custom Domains 탭으로 이동하여 도메인(예: yourcompany.com)을 입력하세요. DNS가 Cloudflare에서 관리되는 경우, 플랫폼이 CNAME 레코드를 구성하고 무료 자동 갱신 SSL 인증서를 즉시 프로비저닝합니다. 도메인 매핑, DNS 또는 서버 보안 관리에 도움이 필요하면 웹사이트 보안 감사 페이지를 확인하세요.

5단계: Wrangler CLI로 배포하기 (직접 업로드)

Git 통합은 대부분의 팀에 적합하지만, Cloudflare의 명령줄 도구인 Wrangler를 사용하여 여러분의 컴퓨터나 기존 파이프라인에서 직접 배포할 수도 있습니다. 이는 빌드가 이미 GitHub Actions나 GitLab CI에서 실행되고 완성된 출력만 업로드하려는 경우에 유용합니다.

Wrangler를 설치하고 인증하세요:

1npm install -g wrangler
2wrangler login

로컬에서 빌드한 다음, 출력 디렉터리를 지정한 프로젝트에 푸시하세요:

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

첫 실행 시 프로젝트가 아직 존재하지 않으면 생성됩니다. CI에서는 대화형 wrangler login 대신 환경 변수로 제공되는 범위가 지정된 API 토큰을 사용하여 브라우저 단계가 필요 없게 하세요:

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

직접 업로드는 Cloudflare의 자체 빌드 단계를 건너뛰어 빌드 환경 문제를 회피하고 툴체인에 대한 완전한 제어권을 제공합니다.

흔한 함정 및 문제 해결

몇 가지 문제가 첫 배포 실패의 대부분을 차지합니다:

  • SPA 경로를 새로 고칠 때 발생하는 404 오류. /dashboard와 같은 클라이언트 사이드 경로는 디스크에 일치하는 파일이 없기 때문에 “Nothing is here yet"을 반환합니다. 해결책은 _redirects의 /* /index.html 200 폴백이며, 해당 파일이 소스 폴더가 아닌 빌드 출력에 위치하는지 확인하는 것입니다.
  • _redirects 또는 _headers가 무시되는 것처럼 보임. 이 파일들은 단순히 저장소가 아니라 게시된 출력 디렉터리에 있어야 합니다. Vite, Astro 또는 SvelteKit에서는 빌드가 그대로 복사하도록 public/(또는 static/) 폴더에 배치하세요.
  • 로컬에서는 빌드에 성공하지만 Cloudflare에서는 실패함. 이는 거의 항상 Node 버전 불일치 또는 누락된 빌드 시점 변수 때문입니다. Node 버전을 고정하고 빌드가 읽는 모든 변수를 다시 선언하세요. 이들은 런타임 바인딩과는 별개입니다.
  • “파일이 너무 많음” 또는 지나치게 큰 배포. 단일 배포는 20,000개 파일로 제한되며 파일당 25 MiB 제한이 있습니다. 대용량 미디어는 정적 번들이 아니라 R2나 이미지 서비스에 속합니다.
  • 릴리스 후 오래된 에셋. app.4f2c.js와 같은 해시된 파일은 적극적으로 캐시할 수 있지만 index.html은 그렇지 않아야 합니다. 앞서 보인 것처럼 HTML은 짧은 캐시에 유지하고 지문이 붙은 에셋은 불변으로 유지하세요.

테스트 및 프로덕션 고려 사항

Cloudflare는 모든 비프로덕션 브랜치와 풀 리퀘스트에 대해 각각 고유한 URL(예: abc123.my-web-app.pages.dev)로 프리뷰 배포를 빌드합니다. 프리뷰는 라이브 사이트와 동일한 에지 네트워크에서 실행되므로 병합 전에 변경 사항을 검토하기에 신뢰할 수 있는 장소입니다.

실제 릴리스의 경우, 몇 가지 제어 장치가 단순한 호스트와 신뢰할 수 있는 워크플로 간의 차이를 만듭니다:

  • 롤백. 모든 배포가 보존되므로 문제가 있는 릴리스는 대시보드에서 이전 빌드를 프로덕션으로 다시 승격시켜 재빌드 없이 몇 초 만에 되돌릴 수 있습니다.
  • 환경 분리. 프로덕션과 프리뷰에 서로 다른 변수를 설정하여 프리뷰 빌드가 실제 데이터가 아닌 스테이징 API를 가리키도록 하세요.
  • 분석 및 Core Web Vitals. 프라이버시 우선이며 쿠키가 없는 Cloudflare Web Analytics를 활성화하여 서드파티 스크립트를 로드하지 않고도 실사용자 LCP, CLS 및 트래픽을 추적하세요.
  • 프리뷰 접근 제어. 프리뷰 URL은 기본적으로 공개됩니다. 브랜치가 미공개 작업을 노출하는 경우, 팀만 열 수 있도록 Cloudflare Access 뒤에 배치하세요.

이를 초기에 마련해 두면 프로젝트가 성장하고 더 많은 사람들이 푸시하더라도 배포가 예측 가능하게 유지됩니다.

핵심 요약

  • Cloudflare Pages는 정적 웹 애플리케이션을 Cloudflare의 글로벌 에지 네트워크에서 호스팅하여 로드 속도를 최적화합니다.
  • GitHub 또는 GitLab을 연결하여 모든 커밋에서 코드를 컴파일함으로써 배포를 자동화하세요.
  • 프레임워크(Astro, Next.js, Hugo, React)에 맞는 빌드 명령어와 출력 디렉터리를 정의하세요.
  • 출력 디렉터리에 간단한 _redirects 및 _headers 텍스트 파일을 사용하여 리디렉션과 보안 헤더를 구성하세요.
  • Cloudflare가 직접 관리하는 무료 자동 갱신 SSL 인증서로 사용자 지정 도메인을 매핑하세요.

웹 인프라 최적화하기

빠르고 안전한 프런트엔드를 배포하려면 올바른 호스팅 아키텍처와 캐싱 규칙을 선택해야 합니다. Mecanik은 웹사이트 개발 서비스 를 전문으로 하며 전문 기술 SEO 감사 서비스 를 제공합니다. 저희는 Core Web Vitals에 최적화되고 Cloudflare에 배포되는 맞춤형 React, Next.js, Astro 플랫폼을 구축합니다. 다음 빌드를 논의하려면 오늘 저희에게 연락하세요.

자주 묻는 질문 (FAQ)

Cloudflare Pages 호스팅이란 무엇인가요? 정적 웹 애플리케이션, React SPA, 정적 사이트 생성기 출력물(Astro나 Hugo 등)을 Cloudflare의 CDN에서 전 세계에 빌드하고 서빙하는 서버리스 프런트엔드 호스팅 플랫폼입니다.

Cloudflare Pages는 서버 사이드 렌더링(SSR)을 지원하나요? 네. Pages는 빌드 과정에서 서버 로직을 서버리스 Cloudflare Workers로 자동 변환하여 SSR 프레임워크(Next.js, Astro, SvelteKit 등)를 지원합니다.

Cloudflare Pages에서 리디렉션을 어떻게 구성하나요? 빌드 출력 디렉터리에 _redirects라는 일반 텍스트 파일을 만들고 소스 경로, 대상 경로, HTTP 상태 코드를 정의하는 리디렉션 규칙을 작성합니다.

Cloudflare Pages는 무료인가요? 네. Cloudflare Pages는 무제한 배포, 무제한 대역폭, 사용자 지정 도메인을 포함하는 넉넉한 무료 요금제를 제공하여 정적 호스팅에 매우 비용 효율적입니다.

Pages에서 사용자 지정 도메인을 어떻게 설정하나요? Pages 프로젝트 대시보드의 Custom Domains 탭으로 이동하여 도메인 이름을 입력하면 Cloudflare가 DNS 레코드를 구성하고 무료 SSL 인증서를 발급합니다.