ViteからNext.jsに移行した際にCloudflare Pagesで発生したNode.js互換性エラーの原因と解決方法

2025-12-09 tue

ViteをCloudflare Pagesで公開していた環境をNext.js（App Router）へ移行したところ、デプロイ後にブラウザで次のエラー画面が表示された。

Node.JS Compatibility Error
no nodejs_compat compatibility flag set
The page you've requested has been built using @cloudflare/next-on-pages, but hasn't been properly configured.

ローカルでは問題なく動作していたため気づかなかったが、Cloudflare PagesはNode.jsとは異なるランタイムで動作するため、Next.jsの実行には追加の設定が必要だった。

なぜViteでは問題なく動いていたのに、Next.jsではエラーになったのか？

ViteはCloudflare Pagesの静的ホスティングで問題なく動作する。

一方で、Next.jsをCloudflare上で動作させる場合は、@cloudflare/next-on-pagesが内部で一部の Node.js API（例：node

） に依存したコードを生成する。

Cloudflare Pages / Workersは Node.jsがそのまま動いているわけではなく、独自のEdge Runtime上で動作する。

そのため、Next.jsが必要とするNode APIを利用するには、Cloudflare側のランタイムを Node 互換モードに切り替える必要がある。

エラーが発生した原因をまとめると次のとおり。

  • Next.jsのコードはNode APIを前提としている
  • しかしCloudflare Pagesの設定でNode互換モードが有効化されていなかった
  • 実行時にCloudflareが「Node APIが使えません」と判断してエラーを出した

ViteはこのようなNode APIの利用を必要としなかったため、問題が起きなかった。

Cloudflare Pagesで必要な設定（解決方法）

エラー文にもある通り、Compatibility flags に nodejs_compat を追加することで解決できる。

手順は以下のとおり。

  1. CloudflareダッシュボードでPagesプロジェクトを開く
  2. 上部の「設定」を選択
  3. 「ランタイム」の項目の「互換性フラグ」にnodejs_compat を追加
  4. ページ上部のプロダクションとプレビューを切り替え、両方に同じフラグを設定する
  5. 「互換性の日付」が古い場合は、2024年以降の新しめの日付に更新しておく

alt

設定後に再デプロイすると、エラーは消える。

互換性フラグ（Compatibility flags）とは？

Cloudflare Workers / Pagesのランタイム挙動を選択するための設定。

Node API・Web API・仕様のバージョンなど、さまざまな機能レベルを制御する。

nodejs_compat はその中で、Workersランタイムに 一部の Node.js API を使えるようにするためのモード。

ただし、Nodeの全機能が使えるわけではなく、

  • fs
  • net
  • child_process

などのNode専用モジュールは依然として利用できない。

そのため、Next.jsのコード中でNode専用の機能を使っている場合は、別のエラーが発生する可能性もある。

互換性の日付とは？

Cloudflare Pages / Workersには「互換性の日付（Compatibility Date）」という設定があり、

アプリをどの時点のランタイム仕様で実行するかを指定するためのものである。

Cloudflareの実行環境は継続的に更新されるため、この日付を設定しておくことで、挙動を特定の仕様に固定でき、予期せぬ変更による不具合を防ぐことができる。

Next.js（特に @cloudflare/next-on-pages）では内部でNode.js APIを利用するため、互換性日付が古いとランタイムとの不整合が発生し、実行時エラーが起こりやすい。

Cloudflare公式では、Node.js互換APIを利用するために 2024-09-23 以降の互換性日付を設定することを推奨している。

next-on-pagesの最低要件自体は「2022-11-30以降」とされているが、実際の動作安定性を考えると、互換性日付はできるだけ新しいものを設定するのが安全である。

まとめ

  • ViteからNext.jsへ移行しCloudflare Pagesにデプロイした際、Node.JS Compatibility Errorが発生した
  • 原因はCloudflare Pages側の Compatibility flags に nodejs_compat が設定されていなかったこと
  • Cloudflareの設定画面から nodejs_compat をProduction / Previewの両方に追加することで解決
  • Compatibility flagsはCloudflareのランタイム挙動を切り替える設定であり、Next.jsを動かす際には特に重要

関連記事