Cloudflare Pages でフロントエンドをデプロイする完全ガイド：React/Vue/Next.js の設定とエラー対処

前言

React プロジェクトを公開しようとして Cloudflare Pages の設定画面を開くと、「Build Command」と「Build Output Directory」で手が止まることがあります。npm run build か npm build か。出力は build か dist か。環境変数はどう設定するか。

本記事では、React、Vue、Next.js を Cloudflare Pages にデプロイする手順を、設定チェックリストと環境変数の設定、5 つのよくあるエラー対処（特に Next.js の nodejs_compat）までまとめて解説します。

なぜ Cloudflare Pages を選ぶのか

Vercel や Netlify があるのに、なぜ Cloudflare Pages かと思うかもしれません。私も最初は Vercel でした。無料版には制限があり、小さなプロジェクトを合わせると月 100GB を超え、速度制限に当たりました。

3 つのプラットフォームを比較すると、無料プランでは Cloudflare Pages がかなり有利です。

無制限トラフィックは大きな魅力です。個人プロジェクトを CF Pages に置いても、流量を気にしなくてよくなりました。

向いているシーン：

• 個人ブログ、ポートフォリオ
• 中小規模フロントエンド（SPA、静的サイト）
• グローバル加速が必要なプロジェクト
• トラフィックが読めないプロジェクト

あまり向かないシーン：

• 複雑な SSR が必要な大規模 Next.js（Vercel ほど Next.js 向きではない）
• ビルドが非常に多いプロジェクト（月 500 回制限）
• Vercel 固有機能（Edge Middleware など）が必須の場合

デプロイ前の準備

1. Cloudflare アカウント
   • Cloudflare で無料登録
   • メール認証後すぐ使えます
2. コードリポジトリ
   • GitHub または GitLab にプッシュ
   • CF Pages は Git から直接ビルドします
3. ビルド設定の把握
   • CRA か Vite か
   • ビルドコマンド（多くは npm run build）
   • 成果物ディレクトリ（CRA は build、Vite は dist）

準備ができたら、実際にデプロイしていきます。

React アプリのデプロイ手順

React はよく使われるフレームワークで、CF Pages に載せた経験から設定の型をまとめました。

手早く React プロジェクトを作る（まだない場合）

# 方式 1：Vite（推奨、ビルドが速い）
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
# 方式 2：Create React App
npx create-react-app my-react-app
cd my-react-app

個人的には Vite を推します。CRA はプロジェクトが大きいとビルドが遅くなりがちです。

Cloudflare Pages 設定チェックリスト

Cloudflare Dashboard → Pages →「プロジェクトを作成」→「Git に接続」でリポジトリを選びます。

注意：

• Vite は Framework preset を None でよい（自動認識）
• CRA は「Create React App」で自動入力される
• 出力ディレクトリを間違えやすい：Vite は dist、CRA は build

環境変数

クライアントで使う変数にはプレフィックスが必須です。

Vite： VITE_（例：VITE_API_URL）

CRA： REACT_APP_（例：REACT_APP_API_URL）

設定方法：

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

1. Cloudflare Pages（推奨）：プロジェクト → Settings → Environment variables → Add variable → Production または Preview
2. コード内：

// Vite
const apiUrl = import.meta.env.VITE_API_URL;
// CRA
const apiUrl = process.env.REACT_APP_API_URL;

ローカル： ルートに .env.local

# Vite
VITE_API_URL=https://api.example.com
VITE_API_KEY=your-api-key-here
# CRA
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-api-key-here

重要： .env.local は Git にコミットしない（.gitignore に .env*.local）。変数変更後は再デプロイが必要です。

SPA ルートの 404 対策

React Router 利用時、リロードで 404 になることがあります。SPA はすべてのパスを index.html に向ける必要があります。

public に _redirects を作成：

/* /index.html 200

すべてのパスを index.html に転送し 200 を返します。保存して再デプロイすればルーティングが直ります。

デプロイ成功の確認

「Save and Deploy」後、Deployments でログを確認します。

成功の目安：

• ログに “Success: Deployed to…”
• xxx.pages.dev の URL が発行される
• サイトが表示される

失敗時：

• ログのエラーを確認
• よくある原因：出力ディレクトリの誤り、Node バージョン（NODE_VERSION=18）、依存関係の問題

Vue アプリのデプロイ手順

Vue は React と似ていますが、細部に注意点があります。

手早く Vue プロジェクトを作る（任意）

# Vite（推奨）
npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install
# Vue CLI
vue create my-vue-app
cd my-vue-app

設定チェックリスト

重点： Vue CLI も Vite も出力は dist。プレフィックスは Vite が VITE_、Vue CLI が VUE_APP_。

環境変数

# .env.local（Vite+Vue）
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=My Vue App
# .env.production（Vue CLI）
VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_TITLE=My Vue App

// Vite
const apiUrl = import.meta.env.VITE_API_BASE_URL;
// Vue CLI
const apiUrl = process.env.VUE_APP_API_BASE_URL;

Vue Router

History モードではリダイレクト必須。public/_redirects に /* /index.html 200（推奨）。

サブパスデプロイ時は vite.config.js で base: '/' を確認。

よくある問題

静的アセット 404： publicPath / base が / か確認。

Vite で “Unknown file extension”： Node が古いことが多い。環境変数に NODE_VERSION=18 を追加して再デプロイ。

Next.js アプリのデプロイ手順（重点）

3 フレームワークの中で Next.js は CF Pages 上で最も手間がかかります。初回は nodejs_compat で半日つまずきました。大規模 SSR が必要なら Vercel も選択肢ですが、静的サイトや軽い SSR なら CF Pages で十分。無料無制限トラフィックは大きいです。

Next.js の特殊性

1. CF Pages は Next.js 専用ではない（Vercel とは違う）
2. 静的エクスポート（簡単）と SSR（アダプター）の 2 方式
3. SSR には @opennextjs/cloudflare（旧 @cloudflare/next-on-pages は非推奨）

方式 1：静的エクスポート（初心者向け）

SSR・API Routes・ISR が不要なら最も簡単です。

向く例： ブログ、ドキュメント、展示サイト、動的データが少ないサイト

手順：

1. next.config.js：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

2. Cloudflare Pages：

制限：

• API Routes 不可
• ISR 不可
• Server Components 不可
• 動的ルートの SSR 不可

方式 2：SSR（OpenNext アダプター）

API Routes、SSR、動的ルートが必要な場合。

npm install @opennextjs/cloudflare

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

Compatibility Flags（最重要）：

1. プロジェクト → Settings → Functions
2. Compatibility flags
3. Configure Production compatibility flag
4. フラグ nodejs_compat を追加
5. Compatibility Date は 2024-09-23 以降

Production と Preview の両方に設定。未設定だとデプロイ後 500 になります。

Edge Runtime：

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

// app/api/hello/route.js
export const runtime = 'edge';
export async function GET(request) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

// pages/api/hello.js
export const config = {
  runtime: 'edge',
};
export default function handler(req) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

サーバー側で動かすファイルにはすべてこの宣言が必要です。

Next.js の環境変数

クライアント（プレフィックス必須）：

NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Next.js Site

サーバー（プレフィックス不要）：

DATABASE_URL=postgresql://...
API_SECRET=your-secret-key

Settings → Environment variables で Production / Preview を選んで追加。

const apiUrl = process.env.NEXT_PUBLIC_API_URL;
const dbUrl = process.env.DATABASE_URL;

Next.js よくあるエラー（5 つ）

エラー 1：nodejs_compat is not defined / 500

Error: The global scope does not support nodejs_compat

原因： nodejs_compat 未設定。

対処： Settings → Functions → Production / Preview 両方に nodejs_compat を追加して再デプロイ。

エラー 2：デプロイ成功だが 404

症状： ビルド成功、xxx.pages.dev が 404、またはトップのみ表示。

原因： Edge Runtime 未設定、出力ディレクトリの誤り。

対処：

1. API Routes / Server Components に runtime = 'edge'
2. 出力は .worker-next（アダプター）または out（静的）
3. 静的なら _redirects を確認

エラー 3：FinalizationRegistry is not defined

原因： Compatibility Date が古い。

対処： Compatibility Date を 2024-09-23 以降に更新して再デプロイ。

エラー 4：ビルドが長い / 失敗

原因： Turbopack、依存が多い、プロジェクトが大きい。

対処：

1. Build command は npx @opennextjs/cloudflare（--turbo 不要）
2. npm prune
3. 可能なら静的エクスポートを検討

エラー 5：Image Optimization エラー

Error: Image Optimization using Next.js' default loader is not compatible with `output: 'export'`.

対処： images: { unoptimized: true }。最適化が必要なら Cloudflare Images、Cloudinary、事前圧縮など。

環境変数管理の応用

開発・プレビュー・本番の使い分けに慣れると運用が楽になります。

3 つの環境

Dashboard での設定

Settings → Environment variables（Production / Preview タブ）

推奨：

1. 本番：API Key などは Secret（例：API_KEY=prod-key-12345）
2. プレビュー：テスト用は Plain text でも可（例：API_KEY=test-key-67890）

ローカル

my-project/
├── .env.local
├── .env.example
├── .gitignore

VITE_API_BASE_URL=http://localhost:3000/api
VITE_API_KEY=local-dev-key
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

.env.local は Git 非コミット。.env.example はコミット。.gitignore に .env*.local。

プレフィックス速見表

覚え方： ブラウザで使う変数はプレフィックス必須。サーバー専用は不要。

効かないときの切り分け

1. プレフィックス（Vite で REACT_APP_、Next.js で NEXT_PUBLIC_ 忘れ）
2. 再デプロイ（Retry deployment または小さなコミット）
3. 環境の取り違え（Production 変数を Preview URL で見ていないか）
4. ビルドログで変数名を検索（Secret は値非表示）
5. 参照方法

// ❌ Vite
const apiUrl = process.env.VITE_API_URL;
// ✅ Vite
const apiUrl = import.meta.env.VITE_API_URL;

応用テクニックとベストプラクティス

デプロイ成功は第一歩。以下で運用を一段上げられます。

カスタムドメイン

xxx.pages.dev から独自ドメインへ。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

1. プロジェクト → Custom domains → Set up a custom domain → 例：blog.example.com
2. DNS： Cloudflare 管理なら CNAME 自動。他社なら手動：

   CNAME  blog  your-project.pages.dev

3. SSL： 無料証明書が 5〜10 分程度で有効。HTTPS 自動。

Preview Deployments

非 main ブランチや PR でプレビュー環境が自動作成されます。

git checkout -b feature/new-button
git add .
git commit -m "Add new button"
git push origin feature/new-button

プレビュー URL 例：https://abc123.your-project.pages.dev

PR で確認し、main マージ後に本番へ。

メリット： ブランチごとに独立プレビュー、PM/デザイナーが本番に影響なく確認。

ビルドキャッシュ

node_modules は CF Pages がキャッシュしますが、さらに最適化できます。

1. pnpm：

   echo "package-manager=pnpm" > .npmrc

2. Build command：pnpm install && pnpm build
3. npm prune

pnpm へ切り替えてビルドが 5 分→2 分になった例もあります。

カスタム Headers

ルートに _headers：

# _headers 例
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer-when-downgrade
/static/*
  Cache-Control: public, max-age=31536000, immutable
/api/*
  Cache-Control: no-cache

再デプロイで反映されます。

まとめ

核心は 3 点です。

1. ビルド設定を押さえる

• Build command（多くは npm run build）
• 出力ディレクトリ（Vite dist、CRA build、Next.js は方式による）
• 環境変数のプレフィックス

2. よくあるハマり

• Next.js の nodejs_compat（未設定で 500）
• 環境変数プレフィックス（Vite VITE_、Next NEXT_PUBLIC_）
• SPA 404（_redirects）

3. Preview を活用

• 本番で直接テストしない
• ブランチで Preview → 問題なければ main へ

初回設定に時間はかかりますが、一度できれば Git Push で自動デプロイ。無料無制限トラフィックは個人運用に効きます。

困ったとき：

• 本記事のエラー集を確認
• ビルドログのメッセージを読む
• Cloudflare Pages Docs

次の一歩：

• 最初のプロジェクトをデプロイ
• カスタムドメインを試す
• Preview Deployments を体験

コメントで質問があれば返信します。デプロイ成功を祈っています。