Cloudflare WorkersでNext.jsを公開する罠｜OpenNextで本番だけ壊れた実録

結論: next buildが通っても、本番で壊れる

先に結論を書く。私が踏んだ罠の多くは、「手元の検査を全部通ったあと」に出た。
lintも型チェックもnext buildも合格して、本番だけが500や404を返す。
だから私は、本番と同じ形のビルドはLinux（GitHub Actions）でしか作らず、公開後の確認はブラウザで実際の画面を開いてやる、という2つの決まりに落ち着いた。

このブログ自体、Next.jsをOpenNextというアダプターでCloudflare Workersに載せている。
2026年10月時点の版はNext.js 16.3.8、@opennextjs/cloudflare 1.20.7、wrangler 4.145.0。
ただ、ここに書く罠を踏んだのは2026年6〜9月で、当時はNext.js 16.2系・@opennextjs/cloudflare 1.19系だった。
10月1日に今の版へ上げたが、OpenNextまわりの罠が今の版でも起きるかは試し直していない。

もう1つ先に断っておく。
ここに書く罠の多くは、このブログではなく、同じ構成（Next.js＋OpenNext＋Cloudflare Workers）で動かしている自分の別の個人サイトで踏んだものだ。
サイトの名前は出さないが、どれも私が運営していて、当時はどれもNext.js 16.2.4・@opennextjs/cloudflare 1.19.4だった。
各節に、踏んだ時期と、このブログか別のサイトかを書き添えておく。

コードを書くのも手元の確認も、ほとんどAIに任せている。
立ち上げはCodexで、今はClaude CodeとCodexの分業だ（併用の実録）。
私の仕事は、頼んで、結果を見て、公開のボタンを押すこと。

実をいうと、この記事は一度後回しにしている。
ラッコキーワードのレビューに書いたとおり、Cloudflareの公開手順は公式ドキュメントと技術メディアが強く、その下のロングテールは小粒だった。
同じ時間なら別の題材のほうが返りが大きいと判断して、寝かせた。
それでも書くことにしたのは、このブログと別の個人サイトで踏んだ罠が、公式ドキュメントを読むだけでは避けにくい形でたまってきたからだ。
公式ドキュメントで裏を取り、公式と私の体験が食い違う所はそのまま両方書く。
公式を確認した日は、どれも2026年10月9日。

踏んだ罠を先に並べておく。右の2列が、手元で気づけなかった理由と、デプロイして起きたことだ。

Windowsでビルドすると、本番もプレビューも全ページ500

2026年6月、別の個人サイトを公開するとき、Claude Codeに、手元のWindowsからnpm run deploy（中身はopennextjs-cloudflare buildとdeploy）を実行させたことがある。
デプロイは成功して公開URLも出たが、開くと全ページが500（Internal Server Error）だった。
next buildもlintも型チェックも通っていたので、コードの問題ではなかった。

ビルドのログには、毎回この警告が出ていた。

WARN OpenNext is not fully compatible with Windows.
WARN While OpenNext may function on Windows, it could encounter unpredictable failures during runtime.

手元で本番と同じ動きを確かめるopennextjs-cloudflare preview（ローカルのWorkersランタイムで動かすコマンド）でも、結果は同じ全ページ500。
2026年9月に、別の個人サイトで設定を確かめようとしたときは、Claude Codeが3回ビルドし直し、previewとwrangler dev --remote（Cloudflareの実際のランタイムを使う）の2通りで試した。
どれも全ページ500で、エラーはChunkLoadError: Failed to load chunk server/chunks/…。
設定を元に戻しても500のままだったので、設定ではなく「Windowsでビルドしたこと」自体が原因だと判断した。
どちらも当時の版（Next.js 16.2系・OpenNext 1.19系）の話で、今の版では試し直していない。
警告の文は、今の版のOpenNextのコードにも残っている。

OpenNextの公式ドキュメントも、Windowsで使えはするが完全な対応は保証しないと書き、代わりの道を3つ挙げている。
WSL（Windows上で動くLinux）、Linuxの仮想マシン、そして開発はふつうのNext.jsの道具で進め、デプロイはLinuxかmacOSで動くGitHub ActionsなどのCI/CDでOpenNextに任せる形だ。
私は3つ目にした。
mainにpushすると、GitHub Actions（ubuntu-latest）の上でnpm ciからnpm run deployまで走る。
これに切り替えたら、本番が開くようになった。

Windowsの手元でやるのは、next devでの表示確認と、設定や依存を変えたときにnpx opennextjs-cloudflare buildが最後まで通るかの確認まで。
Workersの上で動くかどうかは、CIでデプロイしてから本番で確かめる。

手元で起きた小さな罠も3つ書いておく。

• opennextjs-cloudflare buildやプレビューを回したあと、裏で残ったworkerd（ローカルのWorkersランタイム）が.open-next/assetsを掴んだままになり、次のビルドがEBUSYで落ちた。PowerShellのStop-Processでworkerdを止めると通る。
• 開発サーバー（next dev）を動かしたまま同じフォルダでnext buildを回すと、.nextが本番用の中身に置き換わり、devが全ページ404を返した。next buildの直後にdevを起動したときも、2段の動的ルートだけが既存のページまで含めて404になった。どちらも、devを止めて.nextを消し、起動し直せば戻る。新しく足したページが404のときは、既存のページも404かを先に見る。既存も404なら、疑うべきはコードより環境のほうだ。
• PowerShellでnpm run <script> -- --flagと打つと、フラグがスクリプトに渡らなかった（2026年8月）。エラーは出ず、フラグなしの既定の動きで終わるので気づきにくい。bashでは渡るので、bashで確かめたAIは「動作確認済み」と報告してきた。npmは11.4.0でPowerShellからの引数の渡し方を直し（npm/cli #8278、2025年5月）、npm 10系にも10.9.3で同じ修正が入った（npm/cli #8343、2025年6月）。Node 22なら、22.18.0以降に同梱のnpmは10.9.3以上だ。私のPCはNode 22.14.0で、同梱のnpm 10.9.2のまま。修正後の版では試していないので、引数の要る用途は専用のnpm scriptに分けるか、node scripts/x.mjs --flagと直接呼ぶ形にしている。

デプロイの段取り（Re-runの罠・Node 22・独自ドメイン）

「Re-run jobs」では最新のコードが出ない

このブログを公開した日（2026年6月）の話。
初回のpushは、GitHubにCloudflareのAPIトークンを登録する前だったので、デプロイのジョブが失敗した。
ここまでは想定どおり。トークンを登録してから、失敗したrunの「Re-run jobs」を押した。
デプロイは成功したのに、開くとそのあいだに足したページが404だった。

Re-runは、そのrunが最初に走ったコミットをもう一度実行する。
GitHubの公式ドキュメントにも、再実行は元のイベントと同じGITHUB_SHAとGITHUB_REFを使うと書いてある。
私は、古いコードで本番を上書きしていた。

最新のmainを出し直すには、ワークフローのページ右上にある「Run workflow」でブランチにmainを選んで実行する。
このボタンは、ワークフローのトリガーにworkflow_dispatchを書いておかないと出てこない（公式）。
私のdeploy.ymlは、mainへのpushとworkflow_dispatchの2つをトリガーにしている。

deploy.ymlのNodeは22以上にする

別の個人サイトを公開したとき、actions/setup-nodeのnode-versionを20にしていたら（2026年6月）、ビルドまでは通り、デプロイの段階でWrangler requires at least Node.js v22.0.0と出て止まった。
wranglerのpackage.jsonのenginesは、2026年10月9日時点で"node": ">=22.0.0"だ（workers-sdkのpackage.json）。
Cloudflareのwranglerのインストール手順には「Node.jsのCurrent・Active・Maintenance版に対応」とあるだけで、最低バージョンの数字は書かれていなかった。
数字で確かめるなら、package.jsonを見るのが早い。今はdeploy.ymlを22にしている。

独自ドメインは「Custom Domain」で付ける

Workerに自分のドメインを付ける画面（WorkerのSettings → Domains & Routes）には、RouteとCustom Domainの2つの付け方がある。
私が使ったのはCustom Domainのほうで、ドメインをCloudflareで買っていたので、DNSレコードもSSL証明書も自動で用意された。
公式も、Custom DomainはDNSレコードの作成と証明書の発行を代わりに行い、Routeと違ってワイルドカードは使えずホスト名の完全一致になる、と説明している。
公式が挙げる条件は、ドメインがCloudflare上で有効なゾーンになっていること。
同じホスト名にCNAMEレコードが既にあると作れない。

今は設定をwrangler.jsoncに書いて、デプロイのたびに同じ状態になるようにしている。

"preview_urls": false,
"workers_dev": false,
"routes": [
  { "pattern": "example.com", "custom_domain": true }
]

workers_devをfalseにしたのは、*.workers.devのURLにアカウント固有のサブドメインが出るのと、同じページが2つのURLで見える状態を避けたかったからだ。

next buildは通るのに、本番だけ壊れる設定

dynamicParams = falseで、事前生成したページまで404

generateStaticParamsで事前生成している動的ルート（詳細ページ）に、export const dynamicParams = falseが付いていた。
狙いは、一覧に無いURLを404にすること。

本番に出すと、詳細ページが全部404になった。
トップも一覧もsitemap.xmlも200で、sitemapには詳細ページのURLがすべて載っている。
ページだけが出ない。
ローカルのnext buildは「SSG（静的HTMLとして事前生成）」と表示し、next devでも普通に開けたので、手元では気づきようがなかった。
この1行を消したら直った。

Next.jsの公式ドキュメントでは、falseは「generateStaticParamsに含まれないパラメータを404にする」設定で、既定はtrue。
事前生成したページまで消えるとは書かれていない。
OpenNextの公式ドキュメントでも、この件の記載は見つけられなかった。

GitHubには、同じ症状の報告がある（opennextjs-cloudflare #695、2025年6月）。
dynamicParams = falseとgenerateStaticParamsの組み合わせで、事前生成したページがローカルのプレビューで404になったという報告だ。
報告者は、OpenNextのキャッシュの設定（後で書くstaticAssetsIncrementalCache）を入れたら動いたと書き残し、原因ははっきりしないまま閉じられている。
私の2回も、OpenNextのキャッシュは何も設定していなかった。
公式の説明と私の本番で起きたことは食い違っていて、理由は分からないままだ。

今はdynamicParamsを書かず、存在しないパラメータはページの中でnotFound()を返して404にしている。訪れた人から見た動きは同じだ。

情けない話だが、私はこの罠を、別の個人サイト2つで1か月あけて2回踏んだ（2026年7月と8月。
当時はNext.js 16.2.4・OpenNext 1.19.4）。今の版で直っているかは確かめていない。
それ以来、デプロイ後の確認には「動的ルートの詳細ページを実際に1つ開く」を毎回入れている。

middleware.tsをproxy.tsに移したら、デプロイが落ちた

Next.js 16では、devを起動すると「middlewareのファイル規約は非推奨なのでproxyを使って」という警告が出る。
2026年7月、別の個人サイトの手直しをClaude Codeに任せたとき、その中にproxy.tsへの移行も入っていた。
lint・型チェック・next buildが通ったのでpushしたら、GitHub Actionsのデプロイが次のエラーで落ちた。

ERROR Node.js middleware is not currently supported. Consider switching to Edge Middleware.

すぐmiddleware.tsに戻し、今度はnpx opennextjs-cloudflare buildを手元で最後まで通してからpushして、デプロイが通った。
当時の版は、Next.js 16.2.4と@opennextjs/cloudflare 1.19系だ。

Next.jsのproxyのドキュメントでは、proxyはNode.jsランタイムが既定で、runtimeの指定もできない。
OpenNextの公式ドキュメントは、Next.js 15.2で入ったNode.jsのmiddlewareを「まだサポートしていない」と書いていて、10月9日に見てもその一文は残っていた。

ところが、OpenNextの更新履歴を見ると、2026年8月の1.20.3で「Node.jsのmiddleware（proxy.ts）に対応」が入っている（#1309）。
今の1.20.7のコードでは、proxy.tsがあってもビルドを止めず、「実験的な対応で、OpenNextのメンテナーが正式に保守しているものではない。
自己責任で」という意味の警告を出す。ドキュメントと更新履歴で、言っていることが違う。
私は今の版でproxy.tsを試していない。
そのサイトは今もmiddleware.tsのままで、非推奨の警告が出た状態で動かしている。

このとき以来、設定や依存を変えたときは、next buildだけでなくnpx opennextjs-cloudflare buildまで回してからpushしている。
Windowsでビルドしたものは私の環境では動かないが、ビルドが最後まで通るかの確認には使える。

public/_headersは、HTMLには効かない

このブログを含む自分のサイトで、セキュリティ用のヘッダー（X-Frame-Optionsなど4種）をpublic/_headersに書いて本番を確かめたら（2026年9月）、画像やJSの応答には付いているのに、HTMLの応答には付いていなかった。
OpenNextでは、_headersが効くのは静的ファイルの配信（Workers Assets）だけで、Workerが組み立てるHTMLには届かない。
Cloudflareの公式ドキュメントにも、_headersのヘッダーはWorkerのコードが作る応答には付かない、とはっきり書いてある。
ここは公式どおりだった。
HTMLにはnext.config.tsのheaders()で付け、静的ファイル用に_headersも残して、両方に同じものを書いている。

Error 1102は、無料プランのCPU 10msを超えていた

別の個人サイトの本番で、ときどき「Error 1102 Worker exceeded resource limits」が出た（2026年9月）。
厄介なのは、ページ内の移動（Next.jsのLink）が無反応になる形でも出ることだ。
画面の裏で取りに行くデータが1102で失敗し、クリックしても画面が変わらない。
curlで叩くと200が続くので、再現しようとするほど見つからない。

原因はダッシュボードで分かった。
Workers & Pagesから対象のWorkerを開き、Metricsの「Errors by invocation status」を見ると「Exceeded CPU Time Limits」が数えられていた。
同じ画面のCPU時間を見ると、無料プランの上限（1リクエストあたり10ms）を、中央値の時点で大きく超えていた。
半分以上のリクエストが上限を超えていたはずなのに、打ち切られたのはそのうちの一部だけで、ほとんどは普通に返っていた（2026年9月7日にMetricsで確認）。

公式の制限の説明は、無料プランのCPU時間を1リクエスト10ms、有料プランを既定30秒・最大5分としている。
たまに上限を超える程度なら許す余裕があるが、続けて超えるようなら設定した上限で打ち切る、とも書いてある。
私のサイトは「続けて超える」側に見えるのに、打ち切られたのは一部だった。
公式の書き方からは、どこから打ち切られるのかを読み取れなかった。
Error 1102の公式解説は、原因をCPU時間かメモリ（1つのisolateあたり128MB）の超過としている。

対処として、2026年9月7日にWorkers Paidへ切り替えた。
料金ページで確かめると、月5ドルからで、月1,000万リクエストと3,000万CPUミリ秒が込み。
超えた分は100万リクエストごとに0.30ドル、100万CPUミリ秒ごとに0.02ドルだ（2026年10月9日確認）。
契約はアカウント単位で、同じアカウントのWorkerはまとめてこの枠に入る。
暴走したときの課金の保険として、Claude Codeに、そのサイトのwrangler.jsoncでCPU時間の上限を1秒に絞ってもらった。
このlimitsは有料プラン（Standard usage model）でしか使えない設定だ（wranglerの設定の説明、2026年10月9日確認）。
加入したとき、通知の設定には10ドルの予算アラートが自動で入っていた。

"limits": { "cpu_ms": 1000 }

有料に切り替える前に試す価値がありそうな設定もある。
全ページを事前生成していて、あとから再生成（revalidateやISR）を使わないなら、OpenNextの設定で、Next.js本体を起こさずにHTMLを返せる。
ただ、私は有料プランに切り替えたあとに入れたので、無料プランの10msに収まるかは確かめていない。

import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache";

export default defineCloudflareConfig({
  incrementalCache: staticAssetsIncrementalCache,
  enableCacheInterception: true,
});

OpenNextのキャッシュの説明によると、これはビルド時のHTMLを静的ファイルから読む読み取り専用のキャッシュで、再生成は使えない。
enableCacheInterceptionはキャッシュ済みのページでNext.jsのサーバーを呼ばずに済ませる設定で、既定では無効、PPRとは併用できない。

別の個人サイトで2026年9月にこの設定を入れたときは、応答ヘッダーにx-opennext-cache: HITが付き、トップページのTTFB（最初の1バイトが返るまでの時間）が0.32秒から0.09秒に縮んだ（同じURLを2〜3回続けて開いたときの値）。
このブログにも10月1日に入れ、同じヘッダーが付くのを確かめた。
CPU時間がどれだけ減ったかは、まだMetricsで比べていない。

デプロイを重ねてから気づいた、Next.js側の2つ

デプロイの直後、エラー画面の「読み込み直す」が効かない

別の個人サイトをスマホのホーム画面に追加して開いていたとき（2026年9月）、ボタンを押すとエラー画面になり、「読み込み直す」を押しても何も起きないことがあった。
アプリを閉じて開き直すと直る。その日は午前中に6回デプロイしていた。

開きっぱなしの古い画面が、新しいビルドで名前の変わったJSの部品を読みに行って失敗していた（ChunkLoadError）。
ボタンの中身はerror.tsxのreset()で、これは同じ部分を描き直すだけなので、何度押しても同じ失敗を繰り返す。
ホーム画面から開いたページにはタブを閉じる操作が無く、この状態が長く残る。

Claude Codeに直してもらった形は、ボタンをwindow.location.reload()にして、ページごと読み込み直すもの。
ChunkLoadErrorのときは、同じURLにつき60秒に1回だけ自動で読み込み直す（時刻をsessionStorageに残して、無限ループを防ぐ）。
案内文に「サイトを更新した直後は古い画面が残ることがあります」と書き、global-error.tsxも同じ動きにした。

Next.jsの公式ドキュメントを見ると、16.3からretry()が正式になり、ふつうはreset()ではなくretry()を使うよう案内している。
retry()は中身を取り直してから描き直し、reset()は取り直さずに描き直す、という違いだ。
retry()でデプロイをまたいだ状態から戻れるかは、私は試していない。
ページごと読み込み直すほうが確実なので、今もreloadの形にしている。

ページ側でtwitterを書くと、Xのカードが小さくなる

metadataのopenGraphやtwitterは、layoutとpageで中身が混ざらない。
ページ側でtwitter: { title }だけを書くと、layoutに書いたtwitter: { card: "summary_large_image" }が丸ごと消える。
別の個人サイトの実装を任せたCodexがこれを足していて（2026年9月）、そのまま出していたら全記事のXのカードが小さい表示になるところだった。
Claude Codeのレビューで拾えた。

Next.jsの公式ドキュメントにも、metadataは浅くマージされ、openGraphのような入れ子の項目は後のセグメントが丸ごと上書きする、と書いてある。
ここは公式どおりの動きだ。今はページでtwitterを書かず、openGraphから引き継がせている。
手元で本番用のビルドを動かして確かめると、twitter:titleもtwitter:cardも出ていた。

本番の確認は、curlではなくブラウザで

ここまでの罠の多くは、本番で開いて初めて分かるものだった。反映の確認もClaude Codeに任せている。
そのClaude Codeが、別の個人サイトの反映を確かめたとき、curlで取ったHTMLに新しい文言が含まれるかを文字列で調べて、1日で3回判定を外した（2026年8月）。

1. 新しいURLのslugで調べたら、変更前からRSC（サーバーから届く画面の元データ）の中にIDとして埋まっていて、最初から「反映済み」と出た（偽陽性）
2. 「{変数}の{変数}」のような文を探したら、Reactは変数ごとに別のテキストとして出力するので、HTMLにひと続きの文字列が無かった。反映済みなのに20分待った（偽陰性）
3. 今日の日付で表示が切り替わる文を探したら、ブラウザ側で描く部分なので、サーバーが返すHTMLには最初から無かった（偽陰性）

翌月には、このブログでも一度、トップの見出しの変更を「非エンジニア」という語で調べ、別の記事カードにある同じ語に当たって、未反映なのに反映済みと読んだ。

今は、Claude Codeにブラウザで本番を開かせ、実際の画面の文字（DOMのinnerText）を読ませて判定している。
URLには?v=日付のようなキャッシュ回避の文字列も付ける。ブラウザ自体が古いHTMLを持っていることがあるからだ。
curlを使うときは、新しい版にしか無い文字列を選び、変更前のHTMLに無いことを先に確かめる。
Error 1102のように、ブラウザで操作して初めて出る失敗もあった。

まとめ: 公開前と公開後に回している確認

公開前（手元）

• dynamicParams = falseが入っていないか
• proxy.tsを使っていないか（今のOpenNextでは実験的な対応で、ビルドに警告が出る）
• 設定・依存・ルーティングを変えたときは、next buildのあとnpx opennextjs-cloudflare buildまで通す
• devが404を返したら、.nextを消して起動し直してから判断する

デプロイ

• 最新のmainを出すときは「Run workflow」。失敗したrunの「Re-run」は使わない
• deploy.ymlのNodeは22以上

公開後（本番）

• ブラウザで、トップ・新しいページ・動的ルートの詳細ページを1つずつ開く
• HTMLの応答にセキュリティヘッダーが付いているか
• ときどき失敗するなら、Metricsの「Exceeded CPU Time Limits」を見る

どの項目も、一度つまずいてから足したものだ。ほかの作例と、AIに作ってもらうときの段取りはバイブコーディングの始め方にまとめてある。