Cloudflare로 Next.js 블로그 무료 배포하기 — OpenNext와 GitHub Actions 자동 배포 설정법

한 줄 요약: Next.js를 Cloudflare Workers에 올리려면 @opennextjs/cloudflare 어댑터 + wrangler 설정 + API 토큰이 필요합니다. 한 번 세팅해 두면 GitHub에 push할 때마다 GitHub Actions가 빌드부터 배포까지 자동으로 처리합니다. 이 글은 실제로 운영 중인 블로그 구성을 기준으로 설명합니다.

왜 Cloudflare에 배포할까요?

Next.js 배포 하면 Vercel을 가장 먼저 떠올리지만, Cloudflare도 좋은 선택지입니다. 전 세계 엣지 네트워크에서 빠르게 응답하고, 도메인·DNS·보안을 한곳에서 관리할 수 있으며, 개인 블로그 규모에서는 무료 플랜으로 시작할 수 있습니다. Vercel 배포 방법은 Vercel로 블로그 배포하기에서 다뤘으니 두 방법을 비교해 보세요.

Next.js는 Cloudflare 환경에서 바로 돌아가지 않기 때문에 OpenNext의 Cloudflare 어댑터가 빌드 결과물을 Workers가 이해하는 형태로 변환해 줍니다. 이 글에서 쓰는 설정은 모두 이 어댑터의 기본 구성입니다.

배포 전체 흐름 한눈에 보기

1. Cloudflare 계정 만들기 + API 토큰·계정 ID 준비
2. 프로젝트에 어댑터와 wrangler 설치
3. 설정 파일(wrangler.jsonc, open-next.config.ts) 준비
4. 배포 명령 스크립트 등록
5. 로컬에서 미리보기 → 첫 수동 배포
6. GitHub Actions로 자동 배포
7. 커스텀 도메인 연결

1단계. Cloudflare 계정과 인증 정보 준비

1. Cloudflare 대시보드에서 무료 계정을 만듭니다.
2. 계정 ID: 대시보드의 Workers 관련 화면 우측에서 Account ID를 복사해 둡니다.
3. API 토큰: 프로필의 API 토큰 메뉴에서 토큰을 만듭니다. "Edit Cloudflare Workers" 같은 Workers 편집 권한 템플릿을 사용하면 편리합니다.

API 토큰은 비밀번호와 같습니다. 코드나 GitHub 저장소에 직접 적지 말고, 뒤에서 설명할 GitHub Secrets에만 저장하세요.

2단계. 어댑터와 wrangler 설치

Next.js 프로젝트 폴더에서 아래 명령을 실행합니다.

npm install @opennextjs/cloudflare@latest
npm install -D wrangler@latest

wrangler는 Cloudflare의 공식 명령줄 도구이고, @opennextjs/cloudflare는 Next.js 빌드 결과를 Workers용으로 바꿔 주는 어댑터입니다.

3단계. 설정 파일 준비

① wrangler.jsonc

프로젝트 최상위에 Workers 배포 설정 파일을 둡니다. 핵심 항목은 다음과 같습니다.

{
  "main": ".open-next/worker.js",
  "name": "myblog",
  "compatibility_date": "2026-09-26",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}

• main: 어댑터가 만들어 주는 워커 진입 파일 경로
• name: 워커 이름 (workers.dev 주소에 사용됨)
• nodejs_compat: Node.js 호환 기능 활성화 (Next.js에 필요)
• assets: 이미지·CSS 같은 정적 파일 위치

② open-next.config.ts

어댑터 설정 파일입니다. 처음에는 기본값만으로 충분합니다.

import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig({});

캐시를 더 정교하게 쓰고 싶어지면 이후에 R2 같은 저장소를 연결하는 옵션을 추가하면 됩니다.

4단계. package.json에 배포 스크립트 등록

"scripts": {
  "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
  "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy"
}

• npm run preview: 배포 전에 로컬에서 Cloudflare 환경으로 미리 실행
• npm run deploy: 빌드 후 Cloudflare에 실제 배포

5단계. 첫 배포 해보기

터미널에서 아래 순서로 진행합니다.

1. npx wrangler login으로 Cloudflare 계정에 로그인합니다.
2. npm run preview로 로컬에서 정상 동작하는지 확인합니다.
3. npm run deploy로 배포합니다.
4. 완료되면 https://워커이름.계정명.workers.dev 형태의 주소가 출력됩니다.

이 주소로 접속해 사이트가 정상적으로 열리면 첫 배포 성공입니다.

6단계. GitHub Actions로 자동 배포

.github/workflows/deploy.yml 파일을 만들어 main 브랜치에 push될 때마다 자동으로 배포되게 합니다.

name: Deploy to Cloudflare

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: "pnpm"
      - run: pnpm install --no-frozen-lockfile
      - run: pnpm run deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

npm을 쓰는 프로젝트라면 pnpm 관련 단계를 npm 명령으로 바꾸면 됩니다. 리눅스 환경(ubuntu-latest)에서 빌드하는 이유는 OpenNext가 리눅스·macOS 환경에서 가장 안정적이기 때문입니다. Windows에서 빌드가 자주 실패한다면 WSL이나 GitHub Actions를 활용하세요.

GitHub Secrets 등록 방법

1. GitHub 저장소 → Settings → Secrets and variables → Actions를 엽니다.
2. New repository secret을 누르고 이름과 값을 입력합니다.
3. CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID를 등록합니다.

환경 변수 주의점 (가장 많이 막히는 부분)

Supabase 키 같은 값을 쓰는 사이트라면 환경 변수 설정이 중요합니다.

종류	예시	주의점
NEXT_PUBLIC_으로 시작	NEXT_PUBLIC_SUPABASE_URL	빌드할 때 코드에 포함되므로, 빌드가 실행되는 환경(GitHub Actions)에 값이 있어야 함
서버 전용 비밀 값	서비스 롤 키, 이메일 API 키	브라우저에 노출되면 안 됨. 공개 저장소에 올리지 말 것

GitHub Actions에서 빌드하는 경우, 워크플로의 env: 항목에 ${{ secrets.이름 }} 형태로 필요한 값을 모두 넘겨야 합니다. 이 부분을 빼먹으면 배포는 성공해도 사이트에서 데이터를 불러오지 못하는 문제가 생깁니다.

7단계. 커스텀 도메인 연결

1. 도메인을 Cloudflare에서 구입했거나 DNS를 Cloudflare로 옮겨 둡니다.
2. Cloudflare 대시보드에서 해당 Worker를 열고 설정 → 도메인 및 경로(Domains & Routes)로 이동합니다.
3. 커스텀 도메인 추가를 선택해 내 도메인을 입력합니다.
4. 인증서(HTTPS)는 자동으로 발급됩니다.

연결 후에는 www와 루트 도메인 중 대표 주소를 정하고 한쪽에서 다른 쪽으로 이동시키는 설정을 해 두면 검색엔진에도 좋습니다. 도메인 연결 후에는 구글 서치콘솔 등록도 잊지 마세요.

무료 플랜 한도와 주의점

Cloudflare Workers는 무료 플랜으로 시작할 수 있지만 요청 수, 실행 시간, 배포 파일 크기에 제한이 있습니다. 특히 Next.js 앱은 규모가 커지면 압축된 워커 크기가 무료 한도에 걸릴 수 있습니다. 한도 수치는 수시로 바뀌므로 배포 전 공식 문서의 Workers 한도(Limits) 항목을 확인하세요. 한도를 넘는 경우 유료 플랜이 필요할 수 있습니다.

자주 만나는 문제와 해결법

증상	원인	해결
빌드 중 오류 (Windows)	OpenNext의 Windows 환경 불안정	WSL 또는 GitHub Actions(리눅스)에서 빌드
인증 실패 (Authentication error)	API 토큰 권한 부족 또는 계정 ID 불일치	토큰 권한과 Account ID를 다시 확인
배포는 됐는데 데이터가 비어 있음	빌드 시 환경 변수 누락	워크플로 env에 NEXT_PUBLIC 값 전달 확인
워커 크기 초과	번들이 무료 한도 초과	불필요한 패키지 제거 또는 유료 플랜 검토

자주 묻는 질문 (FAQ)

Q1. Vercel과 Cloudflare 중 뭐가 더 좋나요?

Vercel은 Next.js와의 호환성과 설정 편의성이 높고, Cloudflare는 도메인·보안·네트워크를 함께 관리하기 좋습니다. 처음 시작하는 초보자는 Vercel이 더 쉽고, 이미 Cloudflare를 쓰고 있다면 Cloudflare 배포도 훌륭한 선택입니다.

Q2. 자동 배포는 꼭 해야 하나요?

필수는 아니지만, 한 번 설정해 두면 push만으로 배포가 끝나서 매우 편합니다. 수동 배포로 먼저 성공해 본 뒤에 자동화하는 순서를 권합니다.

Q3. 배포가 성공했는데 반영이 안 보여요.

브라우저 캐시일 수 있습니다. 강력 새로고침(Ctrl+F5)을 해 보고, GitHub의 Actions 탭에서 최신 배포가 성공했는지 확인하세요.

Q4. 비용이 갑자기 나올 수 있나요?

무료 플랜은 한도를 넘으면 유료 전환을 안내받는 방식이므로, 자동 청구가 되기 전에 사용량을 대시보드에서 주기적으로 확인하면 됩니다.

마치며

처음에는 설정 파일과 토큰이 낯설지만, 순서대로 한 번만 해 두면 이후에는 글을 쓰고 GitHub에 올리는 것만으로 사이트가 자동 갱신됩니다. 오늘은 우선 로컬 preview → 수동 deploy까지 성공해 보고, 이후에 자동 배포를 붙여 보세요.