궁극의 해결책: OpenNext를 사용하여 Next.js 15를 Cloudflare Pages에서 Workers로 마이그레이션하기

Next.js 15 애플리케이션을 구축하고 @cloudflare/next-on-pages를 사용하여 Cloudflare Pages에 배포하려고 시도했다면, 아마도 장벽에 부딪혔을 것입니다.

악명 높은 "Invalid prerender config" 오류, 정적 라우팅과 동적 라우팅의 일관성 없는 렌더링, 그리고 Edge 런타임 설정 충돌은 커뮤니티의 주요 골칫거리였습니다. 제 포트폴리오 사이트에서 이러한 문제를 디버깅하는 데 몇 시간을 보낸 후, 저는 마침내 확실한 해결책을 찾았습니다. 바로 OpenNext를 사용하여 Cloudflare Pages에서 Cloudflare Workers로 마이그레이션하는 것입니다.

이 가이드에서는 Next.js on Pages가 실패하는 이유와 완벽하고 견고한 배포를 위해 아키텍처를 Cloudflare Workers로 깔끔하게 마이그레이션하는 방법을 정확히 보여드리겠습니다.

문제점: Next-on-Pages의 한계

Cloudflare Pages는 원래 순수한 정적 사이트를 위해 설계되었습니다. @cloudflare/next-on-pages를 통해 서버 사이드 렌더링(SSR) 및 Edge Functions를 지원하도록 발전했지만 Next.js 15의 App Router와의 통합은 여전히 취약합니다.

정적 SSG 라우팅(예: 블로그 게시물)과 동적 edge 라우팅(예: API 엔드포인트 또는 데이터베이스 쿼리)을 혼합하면 빌드 프로세스가 종종 멈춥니다.

Error: Invalid prerender config for /app/[locale]/about
The following routes were not configured to run with the Edge Runtime...

근본적인 문제는 Vercel의 빌드 출력이 함수 구조를 예상하는 방식과 next-on-pages가 Pages 환경을 위해 이를 해석하는 방식 사이의 불일치입니다.

해결책: OpenNext와 Cloudflare Workers

Pages의 빌드 시스템과 씨름하는 대신, 최신 접근 방식은 OpenNext(@opennextjs/cloudflare)를 사용하고 Cloudflare Workers에 직접 배포하는 것입니다.

Workers는 Cloudflare Assets가 정적 파일을 처리하는 동안 Next.js의 SSR 및 API 라우팅 요구 사항과 완벽하게 일치하는 진정한 서버리스 실행 환경을 제공합니다.

단계별 마이그레이션 경로는 다음과 같습니다.

1단계: 종속성 설치

next-on-pages를 제거하고 Cloudflare용 OpenNext를 설치합니다.

npm uninstall @cloudflare/next-on-pages
npm install -D @opennextjs/cloudflare

2단계: OpenNext 구성

프로젝트 루트에 open-next.config.ts 파일을 만듭니다. 이것은 OpenNext에게 Cloudflare를 위해 Next.js 빌드를 조정하는 방법을 알려줍니다.

import type { OpenNextConfig } from 'open-next/types/open-next.js';

export default {
  default: {
    override: {
      wrapper: 'cloudflare-node',
      converter: 'edge',
      incrementalCache: 'dummy',
      tagCache: 'dummy',
      queue: 'dummy',
    },
  },
  middleware: {
    external: true,
    override: {
      wrapper: 'cloudflare-edge',
      converter: 'edge',
      proxyExternalRequest: 'fetch',
    },
  },
} as OpenNextConfig;

3단계: Workers를 위한 Wrangler 설정

Worker 배포를 정의하려면 wrangler.jsonc(또는 wrangler.toml)가 필요합니다. 기본 진입점을 생성된 OpenNext worker로 지정하고 정적 자산을 바인딩하는 방법을 확인하세요.

{
  "main": ".open-next/worker.js",
  "name": "your-project-name",
  "compatibility_date": "2026-06-15",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}

4단계: 빌드 스크립트 업데이트

먼저 Next.js로 빌드한 다음 OpenNext로 처리하도록 package.json을 업데이트합니다.

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

5단계: Edge 구성 정리

OpenNext를 사용하면 더 이상 빌드 시스템을 달래기 위해 모든 동적 파일 상단에 export const runtime = 'edge'를 엄격하게 적용할 필요가 없습니다. OpenNext의 cloudflare-node 래퍼는 Node.js API와 Edge API를 지능적으로 처리하여 코드베이스를 크게 단순화합니다.

Cloudflare R2는 어떻습니까?

이 마이그레이션 중에 Cloudflare R2 버킷을 프로비저닝해야 하는지 궁금할 수 있습니다.

짧은 대답: 아니요, 당장은 아닙니다. Next.js 정적 자산(이미지, CSS, JS 청크)은 wrangler.jsonc에 정의된 Cloudflare Assets 바인딩을 통해 완벽하게 제공됩니다.

그러나 사용자가 업로드한 미디어, 대용량 비디오 또는 대규모 데이터 세트를 처리하도록 애플리케이션이 확장되는 경우 R2는 이 Worker 아키텍처에 원활하게 통합됩니다. wrangler.jsonc에서 R2 버킷을 바인딩하고 Server Actions 또는 API 경로에서 env.MY_BUCKET을 통해 액세스하기만 하면 됩니다.

결과

OpenNext를 사용하여 Cloudflare Workers로 마이그레이션하면 다음을 달성할 수 있습니다.

빌드 오류 제로: 사전 렌더링 구성으로 더 이상 스트레스 받지 마세요.
완벽한 현지화: 국제화된 라우팅(/[locale]/)이 기본으로 작동합니다.
Node.js 호환성: nodejs_compat 플래그는 더 광범위한 npm 패키지 지원을 허용합니다.

Cloudflare Pages는 단순한 정적 사이트에는 환상적이지만, 야심 찬 Next.js 15 애플리케이션의 경우 Cloudflare Workers의 OpenNext가 확실한 해결책입니다.