4장: Cloudflare Pages에 배포하기 — 배포 편¶
만든 웹앱을 5분 만에 공개하기
목차¶
1. Cloudflare Pages란?¶
Cloudflare Pages는 정적 웹사이트를 무료로 배포하는 서비스입니다.
내 컴퓨터(로컬) 인터넷(전 세계)
┌──────────┐ ┌──────────────────┐
│ React 앱 │ ──배포──▶ │ Cloudflare CDN │
│ (npm run │ │ │
│ build) │ │ 누구나 접속 가능 │
└──────────┘ └──────────────────┘
왜 Cloudflare Pages인가요?¶
| 항목 | Cloudflare Pages |
|---|---|
| 가격 | 무료 (월 500회 빌드) |
| 속도 | 전 세계 CDN (빠른 접속) |
| HTTPS | 자동 적용 |
| GitHub 연동 | push하면 자동 배포 |
| 커스텀 도메인 | 무료 연결 |
다른 서비스와 비교¶
| 서비스 | 무료 한도 | 속도 | 설정 난이도 |
|---|---|---|---|
| Cloudflare Pages | 관대함 | 매우 빠름 | 쉬움 |
| GitHub Pages | 충분함 | 빠름 | 쉬움 |
| Vercel | 충분함 | 빠름 | 쉬움 |
| Netlify | 충분함 | 빠름 | 쉬움 |
2. 사전 준비¶
필요한 것¶
체크리스트:
[ ] GitHub 계정 (https://github.com)
[ ] Cloudflare 계정 (https://dash.cloudflare.com/sign-up)
[ ] 이전 장에서 만든 Todo 앱 프로젝트
[ ] Git이 설치된 터미널
프로젝트 빌드 테스트¶
배포 전에 로컬에서 빌드가 정상인지 확인합니다.
cd my-todo-app
npm run build
✓ built in 500ms
dist/ 폴더가 생성되면 성공입니다.
3. GitHub에 올리기¶
Claude Code에 요청¶
이 프로젝트를 GitHub에 올려줘.
새 리포지토리 이름은 my-todo-app으로 해줘.
직접 하는 방법¶
1단계: Git 초기화 (이미 한 경우 스킵)
git init
git add .
git commit -m "feat: Todo 리스트 앱"
2단계: GitHub 리포지토리 생성
# GitHub CLI 사용 (권장)
gh repo create my-todo-app --public --source=. --push
# 또는 GitHub 웹사이트에서 생성 후:
git remote add origin https://github.com/사용자이름/my-todo-app.git
git push -u origin main
3단계: push 확인
git log --oneline
a1b2c3d feat: Todo 리스트 앱
4. Cloudflare 연동¶
4-1. Cloudflare 대시보드 접속¶
- https://dash.cloudflare.com 에 로그인
- 왼쪽 메뉴에서 Workers & Pages 클릭
- Create 버튼 클릭
- Pages 탭 선택
4-2. GitHub 연결¶
1. "Connect to Git" 클릭
2. GitHub 계정 연결 (최초 1회)
3. my-todo-app 리포지토리 선택
4. "Begin setup" 클릭
Cloudflare 대시보드:
┌─────────────────────────────────────┐
│ Connect to Git │
│ │
│ ● GitHub │
│ my-todo-app │
│ 다른-프로젝트 │
│ │
│ [Begin setup] │
└─────────────────────────────────────┘
5. 빌드 설정¶
설정 화면¶
┌─────────────────────────────────────────┐
│ Set build configurations │
│ │
│ Project name: my-todo-app │
│ Production branch: main │
│ │
│ Build command: npm run build │
│ Build output: dist │
│ │
│ Root directory: / (그대로) │
│ │
│ [Save and Deploy] │
└─────────────────────────────────────────┘
핵심 설정값¶
| 항목 | 값 | 설명 |
|---|---|---|
| Framework preset | None 또는 Vite |
Vite 선택 시 자동 설정 |
| Build command | npm run build |
Vite 빌드 명령어 |
| Build output directory | dist |
빌드 결과물 폴더 |
| Root directory | / |
프로젝트 루트 (변경 불필요) |
프레임워크 프리셋이 Vite인 경우¶
Vite를 선택하면 Build command와 Build output이 자동으로 채워집니다. 그대로 사용하면 됩니다.
Save and Deploy 클릭¶
빌드가 시작됩니다:
Building...
├── Installing dependencies... ✅
├── Building project... ✅
├── Deploying to Cloudflare... ✅
└── Done! ✅
Your site is live at:
https://my-todo-app-abc.pages.dev
6. 배포 완료 확인¶
사이트 접속¶
Cloudflare가 알려준 URL로 접속합니다:
https://my-todo-app-abc.pages.dev
확인 체크리스트¶
체크리스트:
[ ] 페이지가 정상적으로 로드되는가?
[ ] 할 일 추가가 되는가?
[ ] 체크박스가 동작하는가?
[ ] 삭제 버튼이 동작하는가?
[ ] 새로고침 후에도 데이터가 유지되는가?
[ ] 모바일에서도 잘 보이는가?
배포 상태 확인¶
Cloudflare 대시보드 → Workers & Pages → my-todo-app:
Deployments:
┌──────────────────────────────────────────────┐
│ Production main a1b2c3d ✅ Success │
│ 2026-05-02 15:30 Build: 12s Deploy: 3s │
└──────────────────────────────────────────────┘
7. 업데이트 방법¶
코드 수정 후 재배포¶
GitHub에 push하면 자동으로 재배포됩니다.
# 코드 수정 후
git add .
git commit -m "feat: 할 일 수정 기능 추가"
git push
로컬 수정 → git push → GitHub 감지 → Cloudflare 자동 빌드 → 자동 배포
Claude Code로 수정하기¶
할 일을 더블클릭하면 수정할 수 있게 해줘.
수정 후에 git commit & push 해줘.
Claude Code가: 1. 코드 수정 2. 커밋 생성 3. GitHub에 push
까지 모두 수행하면 Cloudflare가 자동으로 배포합니다.
배포 내역 확인¶
Deployments 탭:
┌──────────────────────────────────────────────┐
│ Production main b2c3d4e ✅ Success │
│ 2026-05-02 16:00 Build: 11s │
├──────────────────────────────────────────────┤
│ Production main a1b2c3d ✅ Success │
│ 2026-05-02 15:30 Build: 12s │
└──────────────────────────────────────────────┘
실패한 경우¶
빌드가 실패하면 로그를 확인합니다:
Build log:
❌ ERROR: Could not resolve "some-module"
원인을 파악하고 수정 후 다시 push합니다.
8. 커스텀 도메인 (선택)¶
Cloudflare에서 도메인 연결¶
자신의 도메인(예: todo.mysite.com)이 있다면 연결할 수 있습니다.
1. Cloudflare 대시보드 → my-todo-app → Custom domains
2. "Set up a custom domain" 클릭
3. 도메인 입력: todo.mysite.com
4. DNS 설정 안내에 따라 CNAME 레코드 추가
5. HTTPS 자동 적용 (몇 분 소요)
DNS 설정 예시¶
이름: todo
타입: CNAME
값: my-todo-app-abc.pages.dev
문제 해결¶
페이지가 404 에러일 때¶
원인: SPA(Single Page Application) 라우팅 문제
해결: public/_redirects 파일 추가:
/* /index.html 200
빌드 실패할 때¶
# 로컬에서 먼저 빌드 테스트
npm run build
# 에러가 없으면 push
git push
CSS/이미지가 깨질 때¶
원인: 경로 문제. vite.config.js에 base 설정:
export default defineConfig({
plugins: [react()],
base: '/', // 루트 경로에 배포하는 경우
})
전체 워크플로우 요약¶
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 1. 코드 작성 │────▶│ 2. Git push │────▶│ 3. 자동 배포 │
│ (Claude Code)│ │ (GitHub) │ │(Cloudflare) │
└──────────────┘ └──────────────┘ └──────────────┘
↑ │
└──────────── 4. 확인 & 수정 ◀─────────────┘
| 단계 | 명령어/행동 | 결과 |
|---|---|---|
| 코드 작성 | Claude Code에 요청 | 파일 수정 |
| 커밋 | git add . && git commit |
변경사항 저장 |
| push | git push |
GitHub에 업로드 |
| 자동 배포 | Cloudflare가 감지 | 웹사이트 업데이트 |
| 확인 | 배포 URL 접속 | 결과 확인 |
핵심 요약¶
| 개념 | 설명 |
|---|---|
| Cloudflare Pages | 정적 웹사이트 무료 호스팅 |
| GitHub 연동 | push하면 자동 배포 |
| Build command | npm run build |
| Build output | dist 폴더 |
| 배포 URL | https://프로젝트명.pages.dev |
| 커스텀 도메인 | CNAME 레코드로 연결 |
| 업데이트 | 코드 수정 → push → 자동 재배포 |
이것으로 Claude Code로 React 앱을 만들고 배포하는 전체 과정을 배웠습니다!