새 프로젝트 생성 및 Cloudflare Pages 배포

create-cloudflare CLI(C3)을 사용하여 새 프로젝트 생성

create-cloudflare CLI(C3)은 Cloudflare Pages에 적합한 Next.js 사이트를 구성합니다. 터미널에서 다음 명령어를 실행하여 새 Next.js 사이트를 생성하세요:

npm create cloudflare@latest my-next-app -- --framework=next

C3은 일련의 설정 질문을 하고 필요한 종속성(예: Wrangler CLI 및 @cloudflare/next-on-pages 어댑터)을 설치합니다. 프로젝트 생성 후, C3은 기본 Next.js 템플릿을 사용하여 my-next-app 디렉토리를 생성하고 이를 Cloudflare Pages와 완벽히 호환되도록 업데이트합니다.

프로젝트 생성 시, C3은 초기 버전을 Direct Upload를 통해 배포할지 선택할 수 있습니다. 프로젝트 디렉토리에서 다음 명령어를 실행하여 언제든지 애플리케이션을 다시 배포할 수 있습니다:

npm run deploy

Git 통합

기존 프로젝트 또는 수동 프로젝트 설정 및 배포

이미 Next.js 프로젝트가 있거나 C3를 사용하지 않고 수동으로 프로젝트를 생성하고 배포하려는 경우, Cloudflare는 @cloudflare/next-on-pages를 사용하고 README 파일을 참조하여 프로젝트를 개발하고 배포하는 것을 권장합니다.

Git 통합 설정

Direct Upload 배포 외에도 Git 통합을 통해 프로젝트를 배포할 수 있습니다. Git 통합을 통해 GitHub 또는 GitLab 저장소를 Pages 애플리케이션에 연결하고 새로운 커밋이 푸시될 때마다 애플리케이션이 자동으로 빌드되고 배포됩니다.

기존 Pages 애플리케이션에는 Git 통합을 추가할 수 없으므로, 새로운 Pages 애플리케이션을 생성해야 합니다.

새 GitHub 저장소 생성

다음 명령어를 터미널에 입력하여 새 GitHub 저장소를 생성하고 로컬 애플리케이션을 GitHub에 푸시합니다:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin <https://github.com/>/
git push -u origin main

Cloudflare 대시보드를 통해 애플리케이션을 GitHub 저장소에 연결

1. Cloudflare 대시보드에 로그인하고 계정을 선택합니다.
2. 계정 홈에서 Workers & Pages > Create application > Pages > Connect to Git을 선택합니다.
3. GitHub 계정에 대한 접근 권한을 승인합니다.
4. 새 GitHub 저장소를 선택하고 다음 정보를 입력합니다:

설정 옵션 값

Production branch	main
Build command	npx @cloudflare/next-on-pages@1
Build directory	.vercel/output/static

필요에 따라 프로젝트 이름을 사용자 정의할 수 있습니다. 기본값은 GitHub 저장소 이름입니다.

설정을 완료한 후 Save and Deploy를 선택합니다. Pages는 모든 종속성을 설치하고 프로젝트를 지정된 대로 빌드합니다. 새로운 커밋이 푸시될 때마다 프로젝트를 자동으로 재빌드하고 배포합니다.

Next.js 애플리케이션에서 바인딩 사용

바인딩을 통해 애플리케이션이 Cloudflare 개발자 제품(KV, Durable Objects, R2, D1 등)과 상호작용할 수 있습니다. 프로젝트에서 바인딩을 사용하려면 로컬 및 원격 개발을 위한 바인딩을 먼저 설정해야 합니다.

로컬 개발을 위한 바인딩 설정

C3로 생성된 프로젝트는 로컬 개발을 위한 바인딩이 기본적으로 설정되어 있습니다.

로컬 개발에서 바인딩을 사용하려면, 프로젝트의 wrangler.toml 파일을 기반으로 플랫폼 에뮬레이션을 설정하는 setupDevPlatform 함수를 사용합니다.

예를 들어, KV 바인딩을 로컬에서 사용하려면 Next.js 구성 파일에 다음을 추가합니다:

import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev'

if (process.env.NODE_ENV === 'development') {
  await setupDevPlatform()
}

const nextConfig = {}

export default nextConfig

wrangler.toml 파일의 루트에 KV 바인딩을 선언합니다:

name = "my-next-app"

compatibility_flags = ["nodejs_compat"]

[[kv_namespaces]]
binding = "MY_KV"
id = "<YOUR_KV_NAMESPACE_ID>"

배포된 애플리케이션에 바인딩 설정

배포된 애플리케이션에서 바인딩에 접근하려면 프로젝트 설정 페이지에서 필요한 바인딩을 구성하고 연결해야 합니다.

Typescript 프로젝트에 바인딩 추가

TypeScript 프로젝트에서 바인딩에 대한 타입 지원을 설정하려면 새 env.d.ts 파일을 생성하고 CloudflareEnv 인터페이스를 확장합니다.

interface CloudflareEnv {
  MY_KV: KVNamespace
}

바인딩을 애플리케이션에서 사용

로컬 및 원격 바인딩은 @cloudflare/next-on-pages에서 제공하는 getRequestContext 함수를 사용하여 접근할 수 있습니다.

import { getRequestContext } from '@cloudflare/next-on-pages'

export const runtime = 'edge'

export async function GET(request) {
  const myKv = getRequestContext().env.MY_KV
  const kvValue = await myKv.get('kvTest') || false
  return new Response(`The value of kvTest in MY_KV is: ${kvValue}`)
}

Image 컴포넌트

Cloudflare 네트워크는 Vercel 네트워크와 동일한 이미지 최적화 지원을 제공하지 않습니다. <Image /> 컴포넌트를 사용하려면 적절한 로더를 설정해야 합니다.

추천 개발 워크플로우

Cloudflare는 next-on-pages 애플리케이션을 개발할 때 다음 워크플로우를 권장합니다:

1. 표준 Next.js 개발 서버 사용
2. 로컬에서 애플리케이션 빌드 및 미리보기
3. 애플리케이션 배포 및 반복

문제 해결

다음은 next-on-pages를 사용하여 Next.js 애플리케이션을 개발할 때 발생할 수 있는 일반적인 실수와 문제를 해결하는 방법입니다.

Edge 런타임

모든 서버 사이드 라우트는 Edge 런타임 라우트로 구성해야 합니다. 각 서버 사이드 라우트에 export const runtime = 'edge'를 추가해야 합니다.

Not Found 페이지

Next.js는 빌드 과정에서 자동으로 not-found 라우트를 생성합니다. 이러한 라우트가 서버 사이드 로직을 필요로 하면 Node.js 서버리스 함수를 생성할 수 있습니다. 이를 방지하려면 custom not-found 라우트를 제공하고 edge 런타임을 명시적으로 선택해야 합니다.

export const runtime = 'edge'

export default async function NotFound() {
  return (
    // ...
  )
}

generateStaticParams

정적 사이트 생성(SSG) 시 Next.js는 기본적으로 비정적 생성 라우트를 Node.js 서버리스 함수를 통해 처리합니다. 이를 방지하려면 edge 런타임을 선택하거나 dynamicParams를 false로 지정해야 합니다.

상위 수준의 getRequestContext

getRequestContext 함수는 라우트 파일의 최상위 수준에서 호출할 수 없습니다. 요청 처리 과정 내에서 호출해야 합니다.

Learn More

이 가이드를 완료하면 Next.js 사이트를 Cloudflare Pages에 성공적으로 배포한 것입니다. 다른 프레임워크 시작을 위해서는 프레임워크 가이드를 참조하세요.

 

https://developers.cloudflare.com/pages/framework-guides/nextjs/deploy-a-nextjs-site/

Full-stack deployment · Cloudflare Pages docs