cloudflare-nextjs

OpenNext Cloudflare Adapter — Workers 上の Next.js

OpenNext アダプター（@opennextjs/cloudflare）を使用して、Next.js アプリケーションを Cloudflare Workers にデプロイします。このアダプターは標準的な Next.js ビルドを受け取り、package.json のビルドスクリプトを実行した後、Node.js 互換性レイヤー（nodejs_compat）を使って Workers ランタイム上で動作するように出力を変換します。Edge ランタイムではありません。

重要な要件（誤るとビルド／ランタイムが失敗します）

Windows： 完全な動作保証はありません（Next.js のツールに問題があります）。WSL、Linux 仮想マシン、または Linux／macOS の CI を使用してください。既知の問題 #1305 を参照してください。

使い分け：このスキルと nextjs

• nextjs スキル → フレームワーク／App Router／Server Components／Cache Components のパターンを扱います。あらゆるプラットフォーム（Vercel、セルフホストなど）が対象です。async params、proxy.ts への移行、"use cache" に使用します。
• このスキル（cloudflare-nextjs） → OpenNext アダプターを使って Next.js を Workers にデプロイします。対象は wrangler.jsonc、open-next.config.ts、getCloudflareContext、キャッシュ階層、バインディング、スキュー保護、複数 Worker、Workers 固有のエラーです。

proxy.ts に関する注意（Next 16）： Next 16 では middleware.ts が proxy.ts に名称変更されましたが、@opennextjs/cloudflare はまだ proxy.ts を認識しません（issue #1277）。Cloudflare では引き続き middleware.ts を使用してください。ここだけは nextjs スキルのガイダンスが適用されません。

クイックスタート

新規プロジェクト（推奨）

npm create cloudflare@latest -- my-next-app --framework=next --platform=workers

C3 は Next.js アプリをひな形から作成し、@opennextjs/cloudflare をインストールして、wrangler.jsonc、open-next.config.ts、.dev.vars を作成し、package.json のスクリプトを設定します。また、R2 が有効な場合はキャッシュ用の R2 バケットを作成します。

既存の Next.js プロジェクト（1 コマンド）

npx @opennextjs/cloudflare migrate

migrate は次の処理を自動化します。アダプターと wrangler のインストール、wrangler.jsonc／open-next.config.ts／.dev.vars の作成、スクリプトの更新、public/_headers の追加、.gitignore への .open-next の追加、next.config.ts への initOpenNextCloudflareForDev() の組み込み、そして（アカウントで R2 が有効な場合に限り）キャッシュ用 R2 バケットの作成と設定です。

npm install @opennextjs/cloudflare@latest
npm install --save-dev wrangler@latest

4 つのスクリプト

// package.json
{
  "dev":     "next dev",                                                       // fast HMR via Next dev server
  "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",   // build + run in workerd locally
  "deploy":  "opennextjs-cloudflare build && opennextjs-cloudflare deploy",    // build + serve immediately
  "upload":  "opennextjs-cloudflare build && opennextjs-cloudflare upload",    // build + upload a version (gradual rollout)
  "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
}

• dev — 最速のフィードバックループです。ローカルでシミュレートされたバインディングやリモートバインディングを使って getCloudflareContext() が動作するように、next.config.ts に initOpenNextCloudflareForDev() を追加します。
• preview — 実際の Workers ランタイム（Node ではありません）で実行します。ランタイムでのみ発生する問題を検出するため、必ず deploy の前に実行してください。
• deploy — リモートキャッシュを作成した後、wrangler deploy を実行します。アプリはすぐに配信されます。
• upload — リモートキャッシュを作成した後、wrangler versions upload を実行します。自動では配信されません。段階的なデプロイに使用します。

build、preview、deploy、upload はすべて暗黙的に populateCache を呼び出すため、手動で実行する必要はありません。

開発用 next.config.ts

import type { NextConfig } from "next";
const nextConfig: NextConfig = { /* ... */ };
export default nextConfig;

import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
initOpenNextCloudflareForDev();

Cloudflare バインディングへのアクセス — getCloudflareContext()

バインディングに process.env を使用しないでください。 正式な API は、@opennextjs/cloudflare の getCloudflareContext() です。

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

export async function GET() {
  const { env, cf, ctx } = getCloudflareContext();
  await env.MY_KV.put("foo", "bar");
  return new Response(await env.MY_KV.get("foo"));
}

静的ルート（ISR/SSG）では非同期モードを使用する必要があります — 静的生成中にシークレットやローカル値が使用されるため、注意してください。

const { env } = await getCloudflareContext({ async: true });

TypeScript の型: npm run cf-typegen を実行すると cloudflare-env.d.ts が生成されます（バインディングを変更した後は再実行してください）。

リモートバインディング（ローカル開発 → 実際のリソース）: Wrangler 4.36.0 で安定版になりました。古い Wrangler では、initOpenNextCloudflareForDev({ experimental: { remoteBindings: true } }) で有効にし、バインディングオプションでは remote ではなく experimental_remote キーを使用してください。注: リモートバインディングはビルド中にも使用されます。

詳しいパターン（D1/R2/KV/AI/Hyperdrive、Drizzle、Prisma、Stripe）→ references/bindings-and-services.md。

キャッシュ — 3 つのコンポーネント、3 つのティア

OpenNext のキャッシュは、Incremental Cache（ストレージ）、Queue（重複排除／再検証）、Tag Cache（オンデマンドの revalidateTag／revalidatePath）の 3 つの部分で構成されています。

予約済みのバインディング名（再利用しないでください）: ASSETS、WORKER_SELF_REFERENCE、NEXT_INC_CACHE_R2_BUCKET、NEXT_CACHE_DO_QUEUE、NEXT_TAG_CACHE_D1、NEXT_TAG_CACHE_DO_SHARDED、NEXT_CACHE_DO_PURGE、IMAGES。

• 増分キャッシュには Workers KV を使用しないでください — 結果整合性のため、古いデータが無期限に残る可能性があります。
• キャッシュインターセプション + PPR: 現時点では互換性がありません。キャッシュインターセプションはデフォルトで有効ではなく、PPR では動作しません。
• オンデマンド再検証には Tag Cache と Cache Purge コンポーネントの両方が必要です（キャッシュのパージはゾーン／カスタムドメインでのみ動作し、CACHE_PURGE_API_TOKEN + CACHE_PURGE_ZONE_ID のシークレットが必要です）。
• Pages Router の res.revalidate には、WORKER_SELF_REFERENCE という名前のセルフリファレンスサービスバインディングが必要です。
• ヘッダーに関する注意点: Worker は静的アセットの前では実行されないため、public/ と不変のビルドファイルには next.config.ts の headers() が適用されません。public/_headers を使用してください。

詳細（すべてのオプション、環境変数、リージョナルモード、0.6 からの移行）→ references/caching.md と references/known-issues.md。

一般的な統合（概要 — 詳細なパターンはリファレンスを参照）

• Drizzle + D1/Hyperdrive/PG、Prisma + D1/PG/Hyperdrive — react の cache() を使ってリクエストごとにクライアントを作成します。PG プールには maxUses: 1 を指定します。ISR/SSG では getCloudflareContext({ async: true }) を使用します。Prisma では previewFeatures = ["driverAdapters"] が必要です。schema.prisma に出力ディレクトリを指定せず、serverExternalPackages: ["@prisma/client", ".prisma/client"] を設定してください。→ references/bindings-and-services.md
• Stripe — Workers には node:https がないため、httpClient: Stripe.createFetchHttpClient() を渡してください。→ references/bindings-and-services.md
• 画像の最適化 — wrangler.jsonc で images.binding: "IMAGES" を設定するか、ゾーンではカスタムローダー（/cdn-cgi/image/...）を使用します。minimumCacheTTL と dangerouslyAllowLocalIP はサポートされていません。カスタムローダーはミドルウェアをバイパスし、remotePatterns を無視します。→ references/advanced.md
• 環境変数 — Next.js の .env ファイルを使用します（.dev.vars だけでは不十分です）。.dev.vars の NEXTJS_ENV で環境を選択し、デプロイ時に --keep-vars を指定します。シークレットは書き込み専用です。→ references/dev-deploy-and-env.md
• カスタム Worker（scheduled、Durable Object のエクスポートを追加する場合）— 生成された fetch ハンドラーを再エクスポートする Worker を main の参照先にします。→ references/advanced.md
• マルチ Worker（ミドルウェアとサーバーを分割する場合）— Worker ごとのメモリ使用量とコールドスタートを削減します。プレビュー URL、スキュー保護、@opennextjs/cloudflare deploy とは互換性がありません。→ references/advanced.md
• スキュー保護（プレビュー URL に基づくバージョン照合）— cloudflare.skewProtection.enabled、run_worker_first: true、getDeploymentId()、環境変数 CF_WORKER_NAME/CF_PREVIEW_DOMAIN/CF_WORKERS_SCRIPTS_API_TOKEN/CF_ACCOUNT_ID を設定します。Durable Object を持つ Workers では無効です（DO を別の Worker に移動してください）。→ references/advanced.md

よくあるエラー（全項目一覧 → references/error-catalog-extended.md）

1. Worker のサイズ制限超過

"Your Worker exceeded the size limit of 3 MiB"（Free）／"10 MiB"（Paid）。サイズ制限の対象となるのはgzip 圧縮後のサイズのみです。Free の場合は Paid にアップグレードしてください。Paid の場合は、まず npx @opennextjs/cloudflare build を実行してバンドルを分析し、.open-next/server-functions/default/handler.mjs.meta.json を確認します（ESBuild Bundle Analyzer で可視化できます）。未使用の依存関係を削除し、動的インポートを使用してください。

2. 別のリクエストの代わりに I/O を実行できない

グローバルな DB クライアント（例：postgres、pg Pool）を複数のリクエストで再利用しています。クライアントはリクエストハンドラーの内側で作成するか、react の cache() を使用してください。PG プールには maxUses: 1 を指定します。

3. NPM パッケージのインポート／「<package> を解決できませんでした」

nodejs_compat を有効にし、compatibility_date ≥ 2024-09-23 を確認してください。一部のパッケージは workerd エクスポートを提供しています。その場合は、next.config.ts の serverExternalPackages に追加してください（例：@prisma/client、.prisma/client、postgres、jose、react-textarea-autosize、@libsql/isomorphic-ws）。または、.env に WRANGLER_BUILD_CONDITIONS="" と WRANGLER_BUILD_PLATFORM="node" を設定してください。

4. SSRF（CVE-2025-6087）— バージョン < 1.3.0

/_next/image の SSRF。直ちに @opennextjs/cloudflare@^1.3.0（現行：^1.18.1）にアップグレードしてください。

5. チャンク server/chunks/ssr/<name>.js の読み込みに失敗

Turbopack ビルドでアダプターが古くなっています。@opennextjs/cloudflare を最新バージョンにアップグレードするか、webpack に切り替えてください（--turbo を付けずに next build を実行します）。

6. ReferenceError: FinalizationRegistry is not defined

compatibility_date が古すぎます。wrangler.jsonc で "compatibility_date": "2025-05-05"（またはそれ以降）を設定してください。

7. Uncaught ReferenceError: __name is not defined

Wrangler の esbuild keep-names は、実行時に一部のライブラリ（例：next-themes）が eval する生成スクリプト文字列に __name を挿入します。wrangler.jsonc で "keep_names": false を設定してください（Wrangler ≥ 4.13.0 が必要です）。デバッグ時に元の関数名が表示されなくなります。

8. populateCache remote 実行時の「Failed to send request to R2 worker」／403

Cloudflare Access で保護されたアカウントでは、open-next-cache-populate ヘルパーワーカーがブロックされます。このための Access アプリを別途作成しないでください。*.<account>.workers.dev を対象とする既存のアプリに Service Auth ポリシー（Include = Any Access Service Token）を追加し、サービストークンを作成して、CLOUDFLARE_ACCESS_CLIENT_ID／CLOUDFLARE_ACCESS_CLIENT_SECRET をエクスポートしてください。

既知の未解決バグ（最新のトラッカー）

執筆時点で繰り返し発生している問題です。必ずイシュートラッカーを確認してください。

トラッカー全文：https://github.com/opennextjs/opennextjs-cloudflare/issues

機能サポート

関連スキル

参照資料を読み込むタイミング

ソース

• 概要 — https://opennext.js.org/cloudflare
• はじめに — https://opennext.js.org/cloudflare/get-started
• CLI — https://opennext.js.org/cloudflare/cli
• バインディング — https://opennext.js.org/cloudflare/bindings
• キャッシュ — https://opennext.js.org/cloudflare/caching
• 方法：Stripe — https://opennext.js.org/cloudflare/howtos/stripeAPI
• 方法：DB — https://opennext.js.org/cloudflare/howtos/db
• 方法：開発／デプロイ — https://opennext.js.org/cloudflare/howtos/dev-deploy
• 方法：環境変数 — https://opennext.js.org/cloudflare/howtos/env-vars
• 方法：画像 — https://opennext.js.org/cloudflare/howtos/image
• 方法：カスタム Worker — https://opennext.js.org/cloudflare/howtos/custom-worker
• 方法：keep_names — https://opennext.js.org/cloudflare/howtos/keep_names
• 方法：workerd — https://opennext.js.org/cloudflare/howtos/workerd
• 方法：スキュー保護 — https://opennext.js.org/cloudflare/howtos/skew
• 方法：アセット — https://opennext.js.org/cloudflare/howtos/assets
• 方法：複数 Worker — https://opennext.js.org/cloudflare/howtos/multi-worker
• パフォーマンス — https://opennext.js.org/cloudflare/perf
• 既知の問題 — https://opennext.js.org/cloudflare/known-issues
• トラブルシューティング — https://opennext.js.org/cloudflare/troubleshooting
• 0.6 から 1.0.0-beta への移行 — https://opennext.js.org/cloudflare/migrate-from-0.6-to-1.0.0-beta
• 未解決の問題 — https://github.com/opennextjs/opennextjs-cloudflare/issues

バージョン: @opennextjs/cloudflare ^1.18.1 · Next.js 14/15/16 · Wrangler ≥ 3.99.0 · compatibility_date ≥ 2025-05-05 最終確認日: 2026-08-05