Dashboard 접속#

Cloudflare Dashboard에 로그인하고 다음 순서로 진행합니다.

1. 왼쪽 메뉴에서 Build > Compute & AI > Pages 클릭
2. Create application 버튼 클릭
3. Looking to deploy Pages? Get started 클릭
4. Import an existing Git repository Get started 클릭

GitHub 연동#

처음이라면 GitHub 또는 GitLab 계정 연동이 필요합니다.
계정 연동에 관련된 버튼을 누르면 GitHub 권한 승인 페이지로 이동합니다.

Cloudflare가 요청하는 권한은 다음과 같습니다.

1
읽기 권한:
2
  - 저장소 코드 읽기
3
  - 커밋 히스토리 확인
4

5
쓰기 권한:
6
  - Webhook 생성 (푸시 이벤트 감지용)
7
  - PR 코멘트 작성 (Preview URL 공유용)

Cloudflare는 코드를 읽기만 합니다. 코드를 수정하거나 삭제할 수 없습니다.
Webhook은 푸시 이벤트를 감지해서 자동 배포를 트리거하는 용도이고, PR 코멘트는 Preview URL을 공유하기 위한 것입니다.

권한을 승인하면 Cloudflare로 자동으로 리다이렉트됩니다.

저장소 선택#

연동이 완료되면 내 저장소 목록이 보입니다. 배포하고 싶은 저장소를 선택하고 Begin setup 버튼을 클릭합니다.

만약 특정 저장소만 연결하고 싶다면 GitHub 설정에서 조정할 수 있습니다.

• GitHub Settings > Applications > Installed GitHub Apps > Cloudflare Workers and Pages
• Repository access 에서 “Only select repositories” 선택
• 원하는 저장소만 체크

모든 저장소에 권한을 주는 것보다 필요한 것만 선택하는 것을 추천합니다.
보안 측면에서 더 안전하고 관리하기 편합니다.

프로젝트 이름 정하기#

1
Project name: my-awesome-site
2
# 이 이름으로 URL이 만들어집니다
3
# → https://my-awesome-site.pages.dev

프로젝트 이름 규칙:

• 영어 소문자, 숫자, 하이픈(-)만 사용 가능
• 공백이나 특수문자 불가
• 이 이름이 기본 도메인 주소가 됩니다

Production 브랜치 선택#

1
Production branch: main

여기서 선택한 브랜치에 푸시하면 프로덕션 배포가 시작됩니다.
보통 main 또는 master 브랜치를 선택합니다.

팀에서 release라는 별도의 브랜치를 사용한다면 그것을 선택하면 됩니다.
이 브랜치가 실제 사용자에게 보여질 코드입니다.
개발 중인 코드는 다른 브랜치에서 작업하고, 완료된 코드만 이 브랜치로 머지하는 방식으로 운영합니다.

빌드 명령어 설정#

Cloudflare는 package.json과 프로젝트 구조를 분석해서 자동으로 프레임워크를 감지합니다.

Next.js:

1
Framework preset: Next.js (Static HTML Export)
2
Build command: npx next build
3
Build output directory: out

Next.js Static Export를 사용하는 경우입니다.
빌드 명령어와 출력 디렉토리는 프로젝트 설정에 따라 달라질 수 있습니다.
next.config.js에서 output: 'export' 설정이 필요합니다.

1
module.exports = {
2
  output: "export",
3
  images: {
4
    unoptimized: true, // Static Export에서는 이미지 최적화 비활성화 필요
5
  },
6
};

Astro:

1
Framework preset: Astro
2
Build command: npm run build
3
Build output directory: dist

Astro도 기본 설정 기준으로 잘 맞는 편입니다.
SSR이 필요한 경우 Cloudflare 어댑터(@sveltejs/adapter-cloudflare)를 사용하여 Pages Functions 기반으로 배포할 수 있습니다.

프로젝트의 package.json을 확인하면 빌드 명령어를 정확히 알 수 있습니다.

1
{
2
  "scripts": {
3
    "build": "vite build", // 이게 Build command
4
    "dev": "vite",
5
    "preview": "vite preview"
6
  }
7
}

환경변수 (선택사항)#

지금은 비워두고 넘어가도 됩니다. API 키나 환경별 설정은 나중에 Dashboard에서 추가할 수 있습니다.

1
Environment variables: (건너뛰기)

단, 빌드 시점에 필요한 환경변수가 있다면 지금 추가해야 합니다.
예를 들어 VITE_API_URL 같은 빌드 타임 환경변수는 여기서 설정해야 빌드가 제대로 됩니다.
2편에서 환경변수 관리를 자세히 다룰 예정입니다.

빌드 과정 확인#

Cloudflare가 자동으로 다음 작업을 진행합니다.

1
[1/4] Cloning repository...
2
Cloning into '/opt/buildhome/repo'...
3
✓ git clone 완료
4

5
[2/4] Installing dependencies...
6
npm WARN deprecated package@1.0.0
7
✓ npm install 완료 (34.2초)
8

9
[3/4] Building your site...
10
> vite build
11

12
dist/index.html                  0.45 kB
13
dist/assets/index-a1b2c3d4.css  1.23 kB
14
dist/assets/index-e5f6g7h8.js   142.56 kB
15
✓ npm run build 완료 (18.5초)
16

17
[4/4] Deploying to Cloudflare network...
18
Uploading... (156 files)
19
✓ 전 세계 310개 도시에 배포 완료
20

21
Success! Your site is live at:
22
https://my-awesome-site.pages.dev

각 단계의 로그를 실시간으로 볼 수 있습니다. 로그를 보면 어디서 문제가 생겼는지 바로 알 수 있습니다.
소규모 프로젝트는 보통 1-3분 정도 걸리며, 프로젝트 크기와 의존성 개수, monorepo 설정 등에 따라 5분 이상 소요될 수도 있습니다.

빌드가 성공하면 배포 완료 화면이 나옵니다.

1
Deployment successful!
2

3
Visit your site:
4
https://my-awesome-site.pages.dev
5

6
Deployment details:
7
- Commit: abc1234 (Initial commit)
8
- Branch: main
9
- Build time: 52.7초
10
- Deployment ID: def5678
11
- Deployed to: 310+ locations

링크를 클릭하면 바로 배포된 사이트를 확인할 수 있습니다. 첫 배포가 성공했습니다.

Preview 환경이란#

1
Production: main 브랜치 → https://my-site.pages.dev
2
Preview: feature 브랜치 → https://abc123.my-site.pages.dev

각 브랜치가 완전히 독립적인 환경에서 동작합니다. Preview에서 아무리 테스트해도 프로덕션에는 영향이 없습니다.

Preview URL은 브랜치 이름 또는 고유한 해시값을 포함한 형태로 생성됩니다.
여러 명이 동시에 다른 기능을 개발하고 있어도 각자의 Preview 환경이 독립적으로 유지됩니다.

Preview 배포 실습#

실제로 Preview 배포를 만들어봅시다.

1
# 새 기능 브랜치 생성
2
git checkout -b feature/new-design
3

4
# 코드 수정 (예: 헤더 색상 변경)
5
# src/App.css 또는 해당 파일에서 색상 수정...
6

7
# 변경사항 커밋
8
git add .
9
git commit -m "Change header color to blue"
10

11
# GitHub에 푸시
12
git push origin feature/new-design

GitHub에서 Pull Request를 만들면 Cloudflare가 자동으로 반응합니다. 몇 초 안에 PR에 자동으로 코멘트가 달립니다.

1
Preview deployment ready!
2

3
Name: feature/new-design
4
Preview URL: https://abc123.my-site.pages.dev
5
Latest commit: Change header color to blue (a1b2c3d)
6
Build time: 45.3초

이 Preview URL로 접속하면 변경사항을 바로 확인할 수 있습니다. 동료에게 링크를 공유해서 리뷰를 받을 수도 있습니다.

Preview 배포의 실전 활용#

실무에서 이렇게 사용하면 편합니다.

케이스 1: 디자인 변경 검토

1
# 디자이너가 새 디자인 제안
2
git checkout -b design/new-layout
3

4
# 디자인 적용 후 Preview URL 공유
5
# → 디자이너가 직접 확인하고 피드백
6
# → 수정사항 반영 후 다시 푸시하면 Preview URL 자동 업데이트

디자이너와 협업할 때 특히 유용합니다. 스크린샷이나 로컬 서버 공유 대신 Preview URL을 보내면, 실제 환경에서 모바일/데스크톱 모두 직접 확인할 수 있습니다.

케이스 2: 기능 개발 및 QA

1
# 새 기능 개발
2
git checkout -b feature/user-profile
3

4
# Preview URL로 QA 테스트
5
# → QA 팀이 버그 발견 시 PR에 코멘트
6
# → 개발자가 수정 후 다시 푸시
7
# → 문제 없으면 main에 머지

QA 팀과 작업할 때도 편합니다. 매번 빌드 파일을 전달할 필요 없이 Preview URL만 공유하면 됩니다.

케이스 3: 여러 버전 동시 테스트

1
# A안
2
git checkout -b experiment/design-a
3
git push origin experiment/design-a
4
# Preview URL: https://aaa111.my-site.pages.dev
5

6
# B안
7
git checkout -b experiment/design-b
8
git push origin experiment/design-b
9
# Preview URL: https://bbb222.my-site.pages.dev
10

11
# 두 버전을 동시에 비교하고 더 나은 걸 선택
12
# 선택된 버전만 main에 머지

각 Preview 환경은 완전히 독립적입니다. 하나의 PR에서 문제가 생겨도 다른 PR이나 프로덕션에는 영향이 없습니다. 이것이 Preview 배포의 핵심 가치입니다.

Preview 배포 관리#

Preview 배포는 PR이 머지되거나 닫히면 자동으로 삭제됩니다. 따로 정리할 필요가 없습니다.
오래된 PR이 많다면 수동으로 삭제할 수도 있습니다.

Dashboard에서 Deployments 탭을 보면 모든 Preview 배포 목록이 나옵니다. 여기서 개별적으로 삭제하거나 재배포할 수 있습니다.

공식 문서#

• Get started guide - 전체 시작 가이드
• Git integration - Git 연동 상세
• Framework guides - 프레임워크별 가이드
• Build configuration - 빌드 설정
• Limits - 플랜별 제한사항