Cloudflare Pages 완벽 가이드 - 무료로 정적 사이트 배포하기

📋 핵심 내용 요약

• 완전 무료: 무제한 대역폭 + 500회/월 빌드 + 자동 SSL 인증서
• 글로벌 CDN: 200+ 도시 분산 서버로 빠른 속도 제공
• 자동 배포: Git 푸시만으로 자동 빌드 및 전 세계 배포
• 브랜치 프리뷰: PR마다 고유한 미리보기 URL 자동 생성
• 강력한 보안: DDoS 보호 + HTTPS 기본 적용 + WAF 지원

🤖 AI 요약

Cloudflare Pages는 정적 웹사이트 배포를 위한 최고의 무료 플랫폼입니다. 완전 무료이면서도 무제한 대역폭과 글로벌 CDN을 제공하는 것이 가장 큰 장점입니다.

배포 과정: GitHub 저장소와 연동하면 코드를 푸시할 때마다 자동으로 빌드하고 전 세계 200개 이상 도시의 CDN에 배포됩니다. 설정은 매우 간단합니다 - 프레임워크를 선택하고, 빌드 명령어와 출력 디렉토리만 지정하면 됩니다.

개발자 친화적 기능: Pull Request를 생성하면 자동으로 고유한 미리보기 URL이 생성되어 프로덕션에 영향 없이 변경사항을 테스트할 수 있습니다. 환경 변수도 Production과 Preview를 분리하여 관리할 수 있습니다.

성능과 보안: Cloudflare의 강력한 네트워크를 활용하여 빠른 로딩 속도를 보장하며, DDoS 보호와 자동 SSL 인증서로 보안도 완벽합니다. Auto Minify와 Brotli 압축으로 파일 크기를 30-50% 줄일 수 있습니다.

지원 프레임워크: Next.js, SvelteKit, Gatsby, Hugo, Jekyll, Astro 등 거의 모든 정적 사이트 생성기를 지원합니다. 이 블로그도 SvelteKit으로 만들어 Cloudflare Pages에서 호스팅되고 있습니다.

---

정적 사이트를 배포할 곳을 찾고 계신가요? Cloudflare Pages는 완전 무료로 정적 사이트를 호스팅할 수 있는 최고의 플랫폼 중 하나입니다. 이 글에서는 Cloudflare Pages의 모든 것을 자세히 알아보겠습니다.

📌 목차

1. Cloudflare Pages란?
2. 주요 특징과 장점
3. 시작하기 전 준비사항
4. GitHub 연동으로 배포하기
5. 환경 변수 설정
6. 커스텀 도메인 연결
7. 자동 배포 설정
8. 성능 최적화
9. 문제 해결
10. 다른 플랫폼과의 비교

---

Cloudflare Pages란?

Cloudflare Pages는 Cloudflare가 제공하는 JAMstack 웹사이트를 위한 무료 호스팅 플랫폼입니다. Git 저장소와 연동하여 코드를 푸시할 때마다 자동으로 빌드하고 배포할 수 있습니다.

💡 핵심 개념

• 정적 사이트 호스팅: HTML, CSS, JavaScript로 이루어진 정적 파일 호스팅
• 글로벌 CDN: Cloudflare의 전 세계 200+ 도시 네트워크 활용
• Git 기반 워크플로우: GitHub, GitLab과 완벽한 통합
• 자동 빌드: 코드 푸시 시 자동으로 빌드 및 배포

---

주요 특징과 장점

✅ 완전 무료

• 무제한 대역폭: 아무리 트래픽이 많아도 추가 비용 없음
• 무제한 요청: 요청 횟수 제한 없음
• 무료 SSL: 인증서 자동 발급 및 갱신
• 500회/월 빌드: 대부분의 프로젝트에 충분

🚀 빠른 속도

전통적인 호스팅:
사용자 → 단일 서버 (지연 시간 높음)

Cloudflare Pages:
사용자 → 가장 가까운 CDN 노드 (지연 시간 최소)

• 글로벌 CDN: 200개 이상의 도시에 분산된 서버
• 자동 최적화: 이미지, CSS, JS 자동 최적화
• HTTP/3 지원: 최신 프로토콜로 더 빠른 로딩

🔄 자동 배포

# 코드 수정
git add .
git commit -m "Update content"
git push origin main

# → Cloudflare Pages가 자동으로:
# 1. 변경사항 감지
# 2. 빌드 실행
# 3. 전 세계 CDN에 배포
# 4. 완료 알림

🌿 브랜치 프리뷰

Pull Request와 브랜치마다 고유한 미리보기 URL이 생성됩니다:

• 메인 브랜치: https://your-site.pages.dev
• PR/브랜치: https://<commit-hash>.your-site.pages.dev

브랜치 이름이 URL에 포함될 수 있으나 sanitized 되어 표시됩니다.

🛡️ 보안

• DDoS 보호: Cloudflare의 강력한 DDoS 방어
• 자동 SSL: HTTPS 기본 적용
• WAF (선택): 웹 애플리케이션 방화벽 (유료 플랜)

---

시작하기 전 준비사항

1. 필요한 계정

✅ Cloudflare 계정 (무료)
   → https://dash.cloudflare.com/sign-up

✅ GitHub/GitLab 계정 (무료)
   → https://github.com/join

2. 지원하는 프레임워크

Cloudflare Pages는 다양한 프레임워크를 지원합니다:

React 기반

• Next.js (SSG)
• Create React App
• Gatsby
• Remix (SSG)

Vue 기반

• Nuxt (SSG)
• VitePress
• VuePress

기타

• SvelteKit (SSG) ← 이 블로그가 사용!
• Hugo
• Jekyll
• Astro
• Eleventy (11ty)
• Docusaurus

순수 정적

• HTML/CSS/JS: 어떤 정적 사이트든 가능

3. 프로젝트 준비

프로젝트가 정적 사이트를 생성할 수 있어야 합니다:

// package.json 예시
{
  "scripts": {
    "build": "vite build"  // 또는 next build, gatsby build 등
  }
}

빌드 후 생성되는 디렉토리를 확인하세요:

• Next.js: out/
• Gatsby: public/
• SvelteKit: build/
• Hugo: public/

---

GitHub 연동으로 배포하기

1단계: GitHub에 코드 푸시

# 로컬 프로젝트 디렉토리로 이동
cd my-website

# Git 저장소 초기화 (아직 안 했다면)
git init
git add .
git commit -m "Initial commit"

# GitHub 저장소 생성 후 연결
# https://github.com/new 에서 저장소 생성
git remote add origin https://github.com/username/my-website.git
git branch -M main
git push -u origin main

2단계: Cloudflare Pages 프로젝트 생성

2-1. Cloudflare Dashboard 접속

1. https://dash.cloudflare.com 접속
2. 로그인
3. 좌측 메뉴에서 Workers & Pages 클릭

2-2. 새 프로젝트 생성

Create application 버튼 클릭
  ↓
Pages 탭 선택
  ↓
Connect to Git 클릭

2-3. GitHub 연동

![GitHub 연동 화면]

1. Connect GitHub 버튼 클릭
2. GitHub 로그인 및 권한 승인
3. 저장소 선택:
   • 모든 저장소 또는 특정 저장소만 선택 가능
   • 원하는 저장소 선택

3단계: 빌드 설정

프로젝트 설정

Project name: my-website
  - 프로젝트 이름 (URL에 사용됨)
  - 예: my-website → my-website.pages.dev

Production branch: main
  - 프로덕션 배포에 사용할 브랜치
  - 일반적으로 main 또는 master

빌드 설정

Cloudflare Pages는 프레임워크를 자동 감지하지만, 수동 설정도 가능합니다:

Framework preset (자동 감지 또는 수동 선택):

# Next.js 예시
Framework preset: Next.js
Build command: npm run build
Build output directory: out

# SvelteKit 예시
Framework preset: SvelteKit
Build command: npm run build
Build output directory: build

# Gatsby 예시
Framework preset: Gatsby
Build command: npm run build
Build output directory: public

# Hugo 예시
Framework preset: Hugo
Build command: hugo
Build output directory: public

# 순수 정적 사이트
Framework preset: None
Build command: (비워둠)
Build output directory: .

고급 설정 (선택사항):

Root directory: /
  - 프로젝트 루트 디렉토리
  - 모노레포의 경우 packages/web 같은 경로 지정

Environment variables:
  - 빌드 시 필요한 환경 변수
  - 나중에 추가 가능

4단계: 첫 배포

Save and Deploy 버튼을 클릭하면:

1. ✅ GitHub 저장소 복제
2. ✅ 의존성 설치 (npm install)
3. ✅ 빌드 실행 (npm run build)
4. ✅ 빌드 결과물을 CDN에 배포
5. ✅ 배포 완료! 🎉

배포 과정은 일반적으로 2~5분 소요됩니다.

5단계: 사이트 확인

배포가 완료되면 자동으로 URL이 생성됩니다:

https://your-project.pages.dev

Visit site 버튼을 클릭하여 사이트를 확인하세요!

---

환경 변수 설정

많은 프로젝트가 빌드 시 환경 변수를 필요로 합니다.

환경 변수가 필요한 경우

// API 엔드포인트
const API_URL = process.env.PUBLIC_API_URL;

// Google Analytics ID
const GA_ID = process.env.PUBLIC_GA_ID;

// 사이트 URL
const SITE_URL = process.env.PUBLIC_SITE_URL;

환경 변수 추가 방법

Dashboard에서 추가

1. Cloudflare Dashboard → Workers & Pages
2. 프로젝트 선택
3. Settings 탭
4. Environment variables 섹션
5. Add variable 클릭

Variable name: PUBLIC_SITE_URL
Value: https://my-website.pages.dev
Environment: Production (또는 Preview)

Production vs Preview 환경

• Production: 메인 브랜치 배포 시 사용
• Preview: 다른 브랜치/PR 배포 시 사용

예시:

# Production 환경
PUBLIC_SITE_URL: https://my-website.com
PUBLIC_API_URL: https://api.my-website.com

# Preview 환경
PUBLIC_SITE_URL: https://preview.my-website.pages.dev
PUBLIC_API_URL: https://api-staging.my-website.com

환경 변수 변경 후

⚠️ 중요: 환경 변수를 변경하면 재배포가 필요합니다!

Settings → Environment variables → 변경
  ↓
Deployments 탭으로 이동
  ↓
최신 배포 선택
  ↓
Retry deployment 클릭

또는 더미 커밋으로 재배포:

git commit --allow-empty -m "Trigger rebuild"
git push

---

커스텀 도메인 연결

기본 *.pages.dev URL 대신 자신의 도메인을 사용할 수 있습니다.

사전 준비

도메인이 이미 Cloudflare에 등록되어 있다면 매우 쉽습니다:

내 도메인: example.com
원하는 서브도메인: blog.example.com

1단계: 커스텀 도메인 추가

1. Cloudflare Dashboard → Workers & Pages
2. 프로젝트 선택
3. Custom domains 탭
4. Set up a custom domain 클릭

Domain: blog.example.com
  ↓
Continue 클릭

2단계: DNS 자동 설정 (Cloudflare 도메인)

도메인이 Cloudflare에 있다면 자동으로 DNS 레코드가 생성됩니다:

Type: CNAME
Name: blog
Target: your-project.pages.dev
Proxy: ✅ Enabled (orange cloud)

2단계: DNS 수동 설정 (외부 도메인)

도메인이 다른 곳에 있다면 수동으로 DNS 레코드를 추가하세요:

서브도메인 (blog.example.com)

Type: CNAME
Name: blog
Value: your-project.pages.dev
TTL: 자동 또는 3600

Apex 도메인 (example.com)

Apex 도메인(루트 도메인)을 사용하려면:

Cloudflare에서 도메인 관리 시: 자동으로 설정됩니다.

외부 DNS 사용 시:

• CNAME flattening을 지원하는 DNS 제공업체 필요
• 또는 A/AAAA 레코드로 Cloudflare IP를 직접 지정 (Cloudflare 지원 문서 참조)

도메인 등록 업체의 DNS 관리 페이지에서 설정하세요.

3단계: SSL 인증서 (자동)

Cloudflare Pages는 자동으로 SSL 인증서를 발급합니다:

• ✅ Cloudflare Universal SSL 인증서 (자동 발급 및 갱신)
• ✅ 완전 무료

발급 시간: 1~5분

인증서 발급 후 도메인 상태가 Active로 변경됩니다.

4단계: 환경 변수 업데이트

커스텀 도메인을 설정했다면 환경 변수도 업데이트하세요:

기존: PUBLIC_SITE_URL=https://your-project.pages.dev
변경: PUBLIC_SITE_URL=https://blog.example.com

Settings → Environment variables → 수정 → 재배포

DNS 전파 확인

DNS 변경사항이 전파되는 데 시간이 걸립니다:

• 일반적: 5~30분
• 최대: 24시간

확인 방법:

# 터미널에서 확인
dig blog.example.com

# 온라인 도구
https://dnschecker.org

---

자동 배포 설정

Git 기반 워크플로우의 진정한 힘은 자동 배포에 있습니다.

Production 배포 (메인 브랜치)

# 1. 코드 수정
echo "새 글 작성" > new-post.md

# 2. 커밋
git add .
git commit -m "Add new blog post"

# 3. 푸시
git push origin main

# 4. 자동으로:
#    - Cloudflare Pages가 변경사항 감지
#    - 빌드 실행
#    - CDN에 배포
#    - 5분 이내 배포 완료!

Preview 배포 (다른 브랜치)

새 기능을 개발 중이라면:

# 1. 새 브랜치 생성
git checkout -b feature/new-design

# 2. 작업 및 커밋
git add .
git commit -m "New design implementation"

# 3. 푸시
git push origin feature/new-design

# 4. 자동으로 프리뷰 URL 생성:
#    https://feature-new-design.your-project.pages.dev

Pull Request 배포

PR을 생성하면:

# GitHub에서 PR 생성
Create Pull Request
  ↓
Cloudflare Pages가 자동으로:
  - 프리뷰 배포 생성
  - PR에 코멘트로 URL 추가
  - 배포 상태 표시

PR 코멘트 예시:

✅ Deploy Preview ready!

🔗 Preview: https://pr-123.your-project.pages.dev
📝 Commit: abc1234
⏱️ Built in 2m 15s

배포 알림

GitHub 통합 (자동)

• ✅ PR에 배포 상태 자동 표시
• ✅ 배포 완료 시 프리뷰 URL 코멘트
• ✅ 배포 실패 시 에러 메시지

이메일 알림 (선택)

1. Cloudflare Dashboard → Notifications
2. Add 클릭
3. Pages Deploy Failed 선택
4. 이메일 주소 입력

이제 빌드 실패 시 이메일을 받습니다.

Webhook 연동 (고급)

Slack, Discord 등에 알림을 보낼 수 있습니다:

Settings → Webhooks
  ↓
Webhook URL 추가
  ↓
이벤트 선택:
  - Deploy succeeded
  - Deploy failed

---

성능 최적화

Cloudflare Pages는 기본적으로 빠르지만, 더 최적화할 수 있습니다.

1. 자동 최적화 활성화

Cloudflare Dashboard → 도메인 선택 → Speed → Optimization:

Auto Minify

자동으로 파일 압축:

✅ JavaScript
✅ CSS
✅ HTML

코드 크기를 10~30% 줄일 수 있습니다.

Brotli 압축

Gzip보다 더 강력한 압축:

활성화: Speed → Optimization → Brotli

파일 크기를 추가로 15~25% 줄입니다.

2. 이미지 최적화

WebP 사용

// 이미지를 WebP로 변환
import webp from 'imagemin-webp';

// 빌드 스크립트에 추가
imagemin(['images/*.{jpg,png}'], {
  destination: 'build/images',
  plugins: [webp({ quality: 75 })]
});

반응형 이미지

<!-- 다양한 크기 제공 -->
<picture>
  <source srcset="image-small.webp" media="(max-width: 600px)">
  <source srcset="image-medium.webp" media="(max-width: 1200px)">
  <img src="image-large.webp" alt="Description">
</picture>

3. 캐싱 최적화

Cloudflare는 자동으로 최적의 캐싱을 설정하지만, 조정 가능합니다:

Cloudflare Dashboard → Caching → Configuration

Browser Cache TTL:

• Respect Existing Headers (권장)
• 또는 커스텀 설정 (1시간~1년)

Caching Level:

• Standard (권장) - HTML은 캐시하지 않음
• Cache Everything - 모든 것 캐시

4. 빌드 최적화

의존성 최적화

// package.json
{
  "devDependencies": {
    // 개발에만 필요한 패키지는 여기에
    "eslint": "^8.0.0",
    "prettier": "^3.0.0"
  },
  "dependencies": {
    // 빌드에 필요한 패키지만 여기에
    "svelte": "^4.0.0"
  }
}

트리 쉐이킹

번들러가 사용하지 않는 코드를 제거하도록 설정:

// vite.config.js
export default {
  build: {
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true, // console.log 제거
        drop_debugger: true
      }
    }
  }
};

5. 로딩 속도 측정

Google PageSpeed Insights로 측정:

https://pagespeed.web.dev/

목표:

• Performance: 90+ 점
• First Contentful Paint: 1.5초 미만
• Largest Contentful Paint: 2.5초 미만

---

문제 해결

실제로 자주 발생하는 문제와 해결 방법입니다.

1. 빌드 실패

문제: “Output directory not found”

Error: Output directory ".svelte-kit/cloudflare" not found.
Failed: build output directory not found

원인: 잘못된 출력 디렉토리 설정

해결:

Settings → Builds & deployments
  ↓
Build configuration → Edit configuration
  ↓
Build output directory 확인:
  ❌ .svelte-kit/cloudflare  (이건 adapter-cloudflare용)
  ✅ build  (adapter-static용)

Save → Retry deployment

주의사항:

• @sveltejs/adapter-static (정적 사이트) → build/ 디렉토리 사용
• @sveltejs/adapter-cloudflare (Workers/Functions) → .svelte-kit/cloudflare 사용
• 이 가이드는 정적 사이트 배포를 다루므로 adapter-static을 사용합니다

문제: Node.js 버전 오류

Error: The engine "node" is incompatible with this module

해결:

// package.json에 추가
{
  "engines": {
    "node": ">=18.0.0"
  }
}

문제: 의존성 설치 실패

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve

해결:

# 로컬에서 먼저 확인
npm install

# package-lock.json 커밋
git add package-lock.json
git commit -m "Add package-lock.json"
git push

2. 404 에러

문제: SPA 라우팅이 작동하지 않음

직접 접속: https://your-site.com/about → 404 Error

원인: 정적 파일이 없는 경로

해결: Fallback 페이지 설정 (정적 사이트)

// svelte.config.js (SvelteKit)
export default {
  kit: {
    adapter: adapter({
      fallback: '200.html'  // 또는 'index.html'
    })
  }
};

참고: _routes.json은 Cloudflare Pages Functions/Workers 전용 설정입니다. 순수 정적 사이트 배포에는 위의 adapter fallback 설정을 사용하세요.

3. 환경 변수 문제

문제: 환경 변수가 반영되지 않음

확인 사항:

1. ✅ 변수 이름이 정확한가?
2. ✅ Production/Preview 환경을 구분했는가?
3. ✅ 재배포를 했는가?

해결:

# 재배포 트리거
git commit --allow-empty -m "Trigger rebuild"
git push

4. DNS 문제

문제: 커스텀 도메인이 연결되지 않음

확인:

# DNS 확인
dig your-domain.com

# 기대값:
# ANSWER SECTION:
# your-domain.com. 300 IN CNAME your-project.pages.dev.

해결:

1. DNS 레코드가 올바른지 확인
2. 24시간까지 대기 (DNS 전파)
3. 브라우저 캐시 삭제

5. 빌드 시간 초과

문제: 빌드가 20분을 초과함

Error: Build exceeded maximum time limit of 20 minutes

최적화 방법:

1. 의존성 캐싱 확인
2. 불필요한 빌드 단계 제거
3. 병렬 빌드 활성화

// package.json
{
  "scripts": {
    "build": "vite build --parallel"
  }
}

---

다른 플랫폼과의 비교

Cloudflare Pages vs Vercel

특징	Cloudflare Pages	Vercel
가격	완전 무료	무료 (제한있음)
대역폭	무제한	100GB/월 (무료)
빌드 시간	500회/월	6,000분/월
CDN	200+ 도시	70+ 지역
서버리스 함수	Workers (제한적)	✅ 풀 지원
분석	기본	✅ 상세 분석

선택 기준:

• Cloudflare Pages: 순수 정적 사이트, 무제한 대역폭 필요
• Vercel: Next.js SSR, 서버리스 함수 필요

Cloudflare Pages vs Netlify

특징	Cloudflare Pages	Netlify
가격	완전 무료	무료 (제한있음)
대역폭	무제한	100GB/월 (무료)
빌드 분	500회/월	300분/월
폼 처리	❌	✅
리다이렉트	Workers 필요	✅ 내장
플러그인	❌	✅ 풍부

선택 기준:

• Cloudflare Pages: 속도와 대역폭 중시
• Netlify: 폼, 리다이렉트 등 기능 필요

Cloudflare Pages vs GitHub Pages

특징	Cloudflare Pages	GitHub Pages
커스텀 도메인	✅ 무제한	✅ 저장소당 1개 사이트
SSL	✅ 자동	✅ 자동
빌드 파이프라인	✅ 내장	GitHub Actions 필요
프리뷰 배포	✅ 자동	❌
대역폭	무제한	100GB/월 (soft limit)

선택 기준:

• Cloudflare Pages: 프로덕션 사이트
• GitHub Pages: 간단한 문서 사이트

---

실전 예제: SvelteKit 블로그 배포

이 블로그를 예시로 전체 과정을 살펴보겠습니다.

1. 프로젝트 구조

blog-app/
├── src/
│   ├── routes/
│   ├── lib/
│   └── posts/
├── static/
├── svelte.config.js
├── package.json
└── .gitignore

2. Adapter 설정

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: undefined,
      precompress: false,
      strict: true
    })
  }
};

3. 빌드 스크립트

// package.json
{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "@sveltejs/adapter-static": "^3.0.0",
    "@sveltejs/kit": "^2.0.0",
    "svelte": "^4.0.0",
    "vite": "^5.0.0"
  }
}

4. Cloudflare Pages 설정

Project name: blog-lifetech
Production branch: main
Framework preset: SvelteKit
Build command: npm run build
Build output directory: build

5. 환경 변수

# Production
PUBLIC_SITE_URL=https://blog.h3me.xyz
PUBLIC_SITE_NAME=LifeTech Hub
[email protected]
PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

6. 배포 결과

✓ Build completed in 2m 15s
✓ Deploying to Cloudflare's global network
✓ Success! Published to:
  https://blog-lifetech.pages.dev

---

마치며

Cloudflare Pages는 정적 사이트를 배포하는 가장 쉽고 빠른 방법 중 하나입니다. 완전 무료이면서도 무제한 대역폭과 글로벌 CDN을 제공하는 것은 정말 놀라운 일입니다.

시작해보세요!

1. GitHub에 프로젝트 푸시
2. Cloudflare Pages에 연결
3. 빌드 설정
4. 배포!

5분이면 여러분의 사이트가 전 세계에 배포됩니다.

참고 자료

• Cloudflare Pages 공식 문서
• 지원 프레임워크 목록
• Cloudflare Community

---

이 블로그도 Cloudflare Pages에서 호스팅됩니다!

질문이나 피드백이 있으시면 댓글로 남겨주세요. 행복한 코딩 되세요! 🚀