Cloudflare로 Next.js 배포하기

들어가며

안녕하세요. 노머스 프론트엔드 엔지니어 사봉석입니다.

노머스의 대표 서비스인 프롬(fromm) 이 성장함에 따라, 기존 Vercel 중심의 배포 구조에서 벗어나 보다 유연하고 비용 효율적인 인프라 구성을 검토하게 되었습니다. 그 과정에서 Cloudflare 인프라를 활용한 Next.js 배포 방식을 PoC 형태로 검증하게 되었고, 이 글은 해당 과정에서 정리한 내용을 공유하기 위해 작성되었습니다.

이 글에서는 Cloudflare Workers 기반으로 최소한의 스펙을 갖춘 Next.js 애플리케이션을 배포하면서 정리한 기초 개념, 아키텍처, 설정 방법 및 주의사항을 다룹니다. Cloudflare를 처음 접하시거나, Vercel 외의 대안을 검토 중이신 분들께 참고 자료가 되기를 바랍니다.

1. 왜 Cloudflare인가

사내 프로젝트를 Cloudflare 기반으로 이전하기에 앞서, 다음과 같은 기준을 중심으로 검토를 진행하였습니다.

Edge First 아키텍처

• 전 세계 PoP(Point of Presence)에서 요청을 처리합니다.
• 정적 리소스뿐 아니라 SSR 로직 또한 Edge에서 실행할 수 있습니다.

미들웨어 호환성

• wrangler.toml 기반 설정을 통해 Cloudflare Workers 환경에서 미들웨어 사용이 가능합니다.

Workers 기반 실행 환경

• 별도의 Node.js 서버 없이 서버 로직을 실행할 수 있습니다.
• Cold Start 비용이 사실상 존재하지 않습니다.

비용 구조의 단순성

• 트래픽 기반 과금 모델로 비용 예측이 비교적 용이합니다.

보안 및 네트워크 기능 내장

• WAF, DDoS 보호, Rate Limiting 등이 기본 제공됩니다.

캐시 관리

• CDN 캐시를 활용한 정적 자산 및 응답 캐싱이 가능합니다.

비용 효율성 및 확장성

• 2025년 8~10월 기준, 월 평균 수백 GB 이상의 대역폭 사용과 다수의 Edge 요청이 발생하는 서비스 구조에서 Vercel의 대역폭 및 Edge Requests 과금이 주요 비용 증가 요인이었습니다.
• Cloudflare Pages는 대역폭 무제한 정책을 제공하여, 동일 트래픽 조건에서도 네트워크 비용이 사실상 고정 비용에 가깝게 유지됩니다.
• 정적 자산은 Cloudflare CDN에, SSR 및 API 요청은 Workers로 분리함으로써 트래픽 성격에 따른 비용 구조를 명확히 구분할 수 있습니다.
• 해당 구조는 트래픽 증가 시에도 비용이 선형적으로 증가하지 않는 특성을 가지며, 실제 사용량 기준으로 연간 약 93.5%의 비용 절감 효과를 기대할 수 있습니다.

2. 용어 및 개념 정의

이 글에서 사용되는 주요 용어를 간단히 정리합니다.

Cloudflare Pages

• 정적 사이트 및 일부 프레임워크 배포를 지원하는 Cloudflare의 호스팅 서비스입니다.

Cloudflare Workers

• Cloudflare Edge 환경에서 실행되는 서버리스 함수입니다.
• Node.js가 아닌 독자적인 런타임을 사용합니다.

Edge Runtime

• 전통적인 Node.js 런타임과 달리, Edge 환경에서 빠른 실행을 목적으로 설계된 런타임입니다.
• 파일 시스템 접근(fs)이나 일부 Node.js 내장 모듈 사용이 제한되며, 대신 빠른 콜드 스타트와 글로벌 분산 실행이 가능합니다.

Wrangler

• Cloudflare Workers 및 Pages를 배포·관리하기 위한 공식 CLI 도구입니다.

OpenNext

• Next.js 빌드 결과를 다양한 서버리스 및 Edge 환경에서 실행 가능하도록 변환해주는 어댑터 프로젝트입니다.

WAF (Web Application Firewall)

• 웹 애플리케이션을 대상으로 하는 보안 방화벽 기능입니다.

3. 사전 준비

이 글을 따라가기 위해 다음이 필요합니다.

• 프로토타입용 Next.js 프로젝트
• Cloudflare 계정
• Cloudflare Workers 애플리케이션 생성

4. Cloudflare에서 Next.js를 배포하는 방식

Cloudflare는 Next.js를 네이티브로 직접 지원하지 않습니다. 따라서 Next.js 빌드 결과물을 Cloudflare 환경에 맞게 변환해주는 어댑터가 필요합니다.

4.1 Cloudflare Workers + OpenNext (권장)

대상

• SSR, ISR, Middleware, API Routes를 사용하는 경우
• Vercel과 유사한 실행 모델이 필요한 경우

핵심 도구

• @opennextjs/cloudflare

이 글에서는 Workers + OpenNext 방식을 기준으로 설명합니다.

5. 전체 아키텍처 개요

Client
  ↓
Cloudflare CDN
  ↓
Cloudflare Worker
  ├─ Next.js Middleware
  ├─ SSR / RSC
  ├─ API Routes
  ↓
Static Assets (Cloudflare KV / R2)

• 모든 요청은 Cloudflare Edge로 유입됩니다.
• Worker가 Next.js 런타임 역할을 수행합니다.
• 정적 리소스는 CDN 캐시 또는 R2를 통해 서빙됩니다.

6. 프로젝트 설정

6.1 필수 패키지 설치

pnpm add -D @opennextjs/cloudflare  # Cloudflare Workers용 OpenNext 어댑터
pnpm add -D @opennextjs/aws          # OpenNext 기본 패키지
pnpm add -D wrangler                 # Cloudflare Workers CLI

6.2 next.config.js 설정

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone', // 필수 설정
}

module.exports = nextConfig

7. 빌드 및 배포 흐름

7.1 OpenNext 빌드

next build \
  && opennextjs-cloudflare build --skipBuild \
  && cp .open-next/worker.js

• next build : Next.js 프로덕션 빌드 수행
• opennextjs-cloudflare build --skipBuild : 기존 .next 결과물을 기반으로 Cloudflare Workers용 빌드 수행
• cp .open-next/worker.js : Wrangler 설정과 일치하도록 Worker 엔트리 파일 복사

빌드가 완료되면 .open-next/ 디렉토리가 생성되며, Worker 스크립트와 정적 자산이 포함됩니다.

7.2 wrangler 설정

wrangler.toml 파일은 Cloudflare Workers 애플리케이션의 이름, 런타임 동작 기준, 엔트리 포인트, 빌드 및 정적 자산 설정을 정의하는 설정 파일입니다.

name = "프로젝트명" # Cloudflare Workers에 등록될 애플리케이션 이름

compatibility_date = "2025-12-22" # Workers 런타임의 동작 기준이 되는 날짜
compatibility_flags = ["nodejs_compat"] # Node.js API 일부를 사용할 수 있도록 하는 호환 레이어

main = ".open-next/worker.js" # Worker의 엔트리 포인트. OpenNext가 자동 생성한 파일

[build]
command = "pnpm run build" # wrangler deploy 실행 시 사전에 수행될 빌드 명령어

[assets]
directory = ".open-next/assets" # 정적 자산 디렉토리
binding = "ASSETS" # Worker 코드에서 접근할 때 사용할 바인딩 이름

7.3 배포

npx wrangler deploy

8. 환경 변수 관리

Cloudflare는 환경 변수를 빌드 타임과 런타임으로 구분합니다.

구분	용도	예시
Build-time	Next.js 빌드 시 사용	NEXT_PUBLIC_*
Runtime	Worker 실행 시 사용	API_KEY

• NEXT_PUBLIC_ 접두사가 없는 값은 브라우저에 노출되지 않습니다.
• Runtime 환경 변수는 Worker 내부에서만 접근 가능합니다.

9. Middleware 마이그레이션 포인트

다음 API들은 대부분 정상적으로 동작합니다.

• NextRequest.cookies.get / set
• request.nextUrl

미들웨어 적용 범위를 제한하려면 config.matcher 설정이 필요합니다.

// middleware.ts
export const config = {
  matcher: ['/((?!api).*)'],
}

주의사항은 다음과 같습니다.

• Node.js 전용 API 사용이 불가합니다.
• process.env 접근은 Runtime 환경 변수 기준입니다.
• 일부 헤더 조작 로직은 Cloudflare 제약이 존재합니다.

10. 제한 사항 및 주의점

Edge Runtime 제약

• fs, net, child_process 사용 불가

이미지 최적화

• Next Image 일부 옵션에 제약이 있습니다.

ISR

• Vercel과 동작 방식에 차이가 존재합니다.

실서비스 적용 전 기능 단위 검증을 반드시 권장드립니다.

11. 언제 Cloudflare가 적합한가

다음과 같은 경우 Cloudflare 기반 Next.js 배포가 특히 효과적입니다.

• 글로벌 트래픽 비중이 높은 서비스
• SSR 응답 속도가 중요한 서비스
• Edge 기반 인증, A/B 테스트 활용이 필요한 경우
• 인프라 비용 최적화가 중요한 경우

반대로, Node.js 의존도가 높은 서비스라면 Vercel이 더 적합할 수 있습니다.

12. 마무리

인프라에 대한 지식이 거의 없는 상태에서 시작한 작업이었지만, 이번 경험은 Cloudflare를 비롯한 Edge 기반 인프라를 이해하는 중요한 계기가 되었습니다.

실서비스를 곧바로 이전하기보다는, 먼저 프로토타입을 통해 필요한 스펙을 정의하고 기술적 가능성을 검증함으로써 이후 마이그레이션 작업을 보다 안정적으로 준비할 수 있었습니다.

이 글이 Cloudflare로 Next.js 배포를 처음 시도하시는 분들께 시행착오를 줄이는 데 도움이 되는 실질적인 참고 자료가 되기를 바랍니다.