Cloudflare Workers로 Next.js 앱 배포하기 — OpenNext 실전 가이드 2026

CLOUDFLARE WORKERS × NEXT.JS

Next.js 앱을 Cloudflare Workers로 배포하기 — OpenNext 실전 가이드 2026

Vercel 없이, AWS 없이 — 글로벌 엣지 네트워크에 Next.js를 무료로 띄우는 방법

// 이 가이드에서 사용하는 스택

도구	버전	역할
Next.js	15.x	프레임워크
@opennextjs/cloudflare	최신	Next.js → Workers 어댑터
Wrangler	3.x	Cloudflare CLI
Node.js	20 LTS 이상	런타임

① 왜 Cloudflare Workers인가? — 엣지 배포의 장점

Vercel은 편리하지만 트래픽이 늘면 비용이 빠르게 증가합니다. Cloudflare Workers는 전 세계 320개 이상의 PoP(거점)에서 코드가 실행되는 엣지 컴퓨팅 플랫폼으로, 사용자와 가장 가까운 서버에서 응답하기 때문에 레이턴시가 극적으로 낮아집니다.

Cloudflare Workers의 무료 플랜은 하루 10만 건 요청, 10ms CPU 시간을 제공합니다. 개인 프로젝트나 사이드 프로젝트라면 거의 무료로 운영할 수 있습니다. $5/월 Workers Paid 플랜을 사용하면 월 1천만 건 요청과 30ms CPU 시간을 누릴 수 있습니다.

그러나 Next.js는 Node.js 런타임을 기반으로 설계되어 있어, Workers(V8 Isolate 기반)에서 직접 실행할 수 없습니다. 이 문제를 해결한 것이 OpenNext입니다.

② OpenNext란? — Next.js를 어디서나 실행하는 어댑터

OpenNext는 Next.js 빌드 출력물을 각 클라우드 플랫폼에 맞게 변환해주는 오픈소스 어댑터 생태계입니다. @opennextjs/cloudflare 패키지는 Next.js 앱을 Cloudflare Workers에서 실행 가능한 형태로 변환합니다.

💡 지원 범위 (2026년 기준)

App Router, Route Handlers, Edge Runtime 미들웨어, ISR(캐시), 이미지 최적화(일부)가 지원됩니다. Pages Router는 부분 지원이므로 신규 프로젝트는 App Router를 권장합니다.

③ 프로젝트 세팅 — 처음부터 시작하기

먼저 Next.js 프로젝트를 생성하고 필요한 패키지를 설치합니다.

# 1. Next.js 프로젝트 생성
npx create-next-app@latest my-app --app --typescript
cd my-app

# 2. OpenNext Cloudflare 어댑터 설치
npm install -D @opennextjs/cloudflare wrangler

그 다음 프로젝트 루트에 wrangler.toml 파일을 생성합니다.

# wrangler.toml
name = "my-app"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
main = ".open-next/worker.js"

[assets]
directory = ".open-next/assets"
binding = "ASSETS"

그리고 open-next.config.ts 파일을 루트에 만듭니다.

// open-next.config.ts
import type { OpenNextConfig } from "@opennextjs/cloudflare";

const config: OpenNextConfig = {
  default: {
    override: {
      wrapper: "cloudflare-node",
      converter: "edge",
    },
  },
};

export default config;

④ 환경변수 설정 — API 키를 안전하게 주입하는 방법

Cloudflare Workers에서 환경변수는 wrangler.toml 또는 Cloudflare Dashboard에서 관리합니다. 민감한 값(API 키 등)은 절대 wrangler.toml에 평문으로 저장하지 마세요.

# Secret 등록 (Cloudflare Workers Secrets)
npx wrangler secret put GEMINI_API_KEY
# 프롬프트에 실제 키 값 입력

코드에서는 두 가지 방법으로 환경변수에 접근할 수 있습니다.

// app/api/route.ts — 권장 패턴 (로컬/CF 환경 모두 지원)
import { getCloudflareContext } from "@opennextjs/cloudflare";

export async function GET() {
  let apiKey = process.env.GEMINI_API_KEY;
  const ctx = await getCloudflareContext({ async: true });
  if (ctx?.env?.GEMINI_API_KEY) apiKey = ctx.env.GEMINI_API_KEY;
  // ...
}

⚠️ 주의

Cloudflare Workers는 Node.js의 process.env를 완전히 지원하지 않습니다. 로컬 개발 시에는 .dev.vars 파일에 변수를 저장하세요 (wrangler dev가 자동으로 로드합니다).

⑤ 빌드 & 배포 — 한 번에 보는 명령어 정리

package.json의 scripts를 아래와 같이 설정하면 편리합니다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "pages:build": "opennextjs-cloudflare build",
    "preview": "opennextjs-cloudflare build && wrangler dev",
    "deploy": "opennextjs-cloudflare build && wrangler deploy"
  }
}

명령어	설명
npm run dev	Next.js 로컬 개발 서버
npm run preview	Cloudflare Workers 로컬 에뮬레이션
npm run deploy	Workers 빌드 + 실제 배포

⑥ 자주 발생하는 오류와 해결법

🐛 오류 1: "Cannot use require() in Workers"

wrangler.toml에 compatibility_flags = ["nodejs_compat"]가 빠진 경우 발생합니다. 반드시 추가하세요.

🐛 오류 2: "Script size limit exceeded"

Workers 무료 플랜의 스크립트 크기 제한(1MB)을 초과한 경우입니다. next.config.js에서 output: 'export' 대신 서버 컴포넌트를 최적화하거나, Workers Paid 플랜(제한 없음)으로 업그레이드가 필요합니다.

🐛 오류 3: 로컬에선 되는데 배포 후 500 에러

Cloudflare Dashboard → Workers & Pages → 해당 워커 → 로그에서 실시간 에러 확인. wrangler tail 명령으로 실시간 로그를 스트리밍해서 디버깅할 수 있습니다.

🚀 정리

Cloudflare Workers + OpenNext 조합은 Next.js App Router 기반 프로젝트를 글로벌 엣지에 무료(또는 저비용)로 배포할 수 있는 강력한 선택지입니다. 초기 설정 러닝커브가 있지만, 한 번 구성해 두면 GitHub Actions와 연동해 CI/CD 파이프라인을 완성할 수 있습니다.

⚠️ 면책 고지
본 포스팅은 2026년 3월 기준 정보를 바탕으로 작성되었습니다. OpenNext, Cloudflare Workers, Next.js는 빠르게 업데이트되므로 최신 공식 문서(developers.cloudflare.com, opennext.js.org)를 함께 참고하시기 바랍니다. 코드 예시는 참고용이며 프로덕션 환경에서의 검증은 직접 확인하시기 바랍니다.