Next.js 앱을 Cloudflare Pages에 배포하는 방법

왜 Cloudflare Pages인가

Vercel은 편리하지만 무료 티어 제한이 빡빡합니다. Cloudflare Pages는 무제한 대역폭, 빠른 글로벌 CDN, 그리고 D1/R2/KV 같은 서버리스 스토리지와의 자연스러운 통합을 제공합니다.

핵심 설정

npm install @cloudflare/next-on-pages

next.config.ts에서 Edge Runtime을 기본으로 설정하고, 모든 서버 컴포넌트에 export const runtime = "edge"를 추가합니다.

빌드 명령어

npx @cloudflare/next-on-pages

출력 디렉토리는 .vercel/output/static입니다. Cloudflare Pages 프로젝트 설정에서 이 경로를 지정합니다.

자주 만나는 문제

1. Node.js API 사용 불가

Edge Runtime에서는 fs, path 등 Node.js 네이티브 모듈을 사용할 수 없습니다. 데이터는 D1, KV, 또는 정적 import로 처리합니다.

2. 빌드 시 환경변수

Cloudflare Pages 대시보드에서 환경변수를 설정하거나, wrangler.toml의 [vars]에 non-secret 값을 넣습니다.

3. middleware 제한

middleware.ts는 동작하지만, next/server의 일부 기능이 제한됩니다. 쿠키 기반 인증은 정상 동작합니다.

결론

초기 설정만 잘 잡으면 Cloudflare Pages는 Next.js 풀스택 앱을 무료로 운영할 수 있는 최고의 선택지입니다.