# 40 · Cloudflare Pages 배포

**언제 읽나**: 정적 사이트·SPA를 배포할 때.
**전제**: git 연동 없이 디렉터리를 직접 올리는 방식이다.

---

## 설정 파일

프로젝트 루트에 `wrangler.toml`:
```toml
name = "my-project"
compatibility_date = "2026-10-01"
pages_build_output_dir = "dist"
```

## 배포 명령

```bash
# wrangler.toml이 있는 경우 — 루트에서, 경로 인자 없이
npx wrangler pages deploy --branch=main --commit-dirty=true

# 빌드가 필요한 SPA
npm run build
npx wrangler pages deploy dist --project-name <proj> --branch main --commit-dirty=true
```

---

## 함정

| 상황 | 조치 |
|---|---|
| `pages project create`가 Workers 배포로 넘어가며 실패 | 최신 wrangler의 동작이다. 이미 만들어진 프로젝트는 `pages deploy`만 쓰면 된다. 신규 생성이 막히면 `--force`를 1회만 사용 |
| 특정 페이지를 홈으로 만들고 싶다 | 출력 폴더에 `_redirects` 파일 생성: `/ /portfolio.html 200` |
| `_redirects`를 넣었는데 URL이 바뀐다 | 정상이다. Pages가 `.html`을 확장자 없는 경로로 **자동 308 리다이렉트**한다. 결과는 `/` → `/portfolio` |
| 루트 `index.html`에 접근이 안 된다 | 위 설정의 부작용이다. 남겨야 하면 다른 파일명으로 옮긴다 |
| 개인정보가 들어간 파일을 올릴 뻔했다 | 마스킹 빌드를 따로 만들어 그것만 올린다. 배포 전 `grep`으로 실제 번호·이메일이 없는지 확인 |

비밀값: `npx wrangler pages secret put NAME --project-name <proj>` — 코드·toml에 두지 않는다.

---

## 배포 후 확인 (반드시)

```bash
curl -sI https://<url>/ | head -1
curl -sL https://<url>/<page> | grep -o "<title>[^<]*</title>"
```

❌ **"Deployment complete" 로그를 서빙 증거로 쓰지 마라.** 의도한 문서가 실제로 나오는지 확인한다.
파일(이미지·zip 등)을 올렸으면 `content-type`도 확인한다. `text/html`이 나오면 그 파일은 없는 것이다(404 폴백).

```bash
curl -sI https://<url>/assets/x.jpg | grep -i content-type   # image/jpeg 여야 정상
```

배포 직후에는 전파 지연이 있을 수 있다. 몇 초 뒤 다시 확인한다.