Node.js 互換性

Worker を書くとき、npm ↗ からパッケージを import することがあります。多くの npm パッケージは Node.js runtime ↗ の API に依存しており、これらの Node.js API がなければ動きません。

Cloudflare Workers は、Node.js API のサブセットを次の 2 つの形で提供します。

1. Workers Runtime が提供する組み込み API として。これらの API の多くは、対応する Node.js API の完全な実装です。一部は部分的なサポートです。
2. Wrangler が Worker のコードに追加するポリフィル（シム）実装として。モジュールの import はできますが、API メソッドを呼ぶとエラーになります。

compatibility date が 2026-08-04 以降の場合、Workers は nodejs_compat と nodejs_compat_v2 の両方を既定で有効にします。組み込みの Node.js API とポリフィルは、追加設定なしで使えます。

これらの compatibility date では、compatibility date 自体が同じ動作を有効にするため、nodejs_compat と nodejs_compat_v2 は使いません。既存プロジェクトは、compatibility date を更新するときにこれらのフラグを削除する必要はありません。新規の設定では省略します。

compatibility date が 2024-09-23 から 2026-08-03 までの場合は、Wrangler 設定ファイル に nodejs_compat compatibility flag を追加してオプトインします。

{
	"compatibility_date": "2026-08-03",
	"compatibility_flags": ["nodejs_compat"]
}

compatibility_date = "2026-08-03"
compatibility_flags = [ "nodejs_compat" ]

compatibility date が 2026-08-04 以降で Node.js 互換を完全にオフにするには、肯定フラグがあれば削除します。そのうえで no_nodejs_compat と no_nodejs_compat_v2 の両方を追加します。設定例は Node.js compatibility flag を参照してください。

この節で「🟢 サポート済み」とある Node.js の runtime API は、現在 Workers Runtime でネイティブサポートされています。「🟡 一部サポート」の項目は使える API を含みますが、Node.js API の全体は実装していません。

非推奨または実験的な Node.js API ↗ と、サーバーレスの文脈に合わない API は、この節のサポート対象一覧に含めていません。これらの API 向けの import 専用スタブの一部は、機能しないスタブモジュール に別掲しています。

特に記載がない限り、Workers における Node.js API のネイティブ実装は、Node.js の Current リリース ↗ の実装に合わせることを意図しています。

使いたい API がなく、Workers でのサポートを提案したい場合は、GitHub の Node.js APIs discussions category ↗ に投稿またはコメントしてください。

一部の Node.js モジュールは、機能しないスタブとして利用できます。スタブは import や require はできますが、元の Node.js API の実装は提供しません。モジュールの存在を確認するパッケージが Workers 上で読み込めるようにするためのもので、アプリケーションコードから直接使う用途には向きません。

次のスタブは、nodejs_compat compatibility flag が有効で、Worker の compatibility date が表の日付以降の場合にだけ、自動で有効になります。より早い日付で有効にするには、対応する enable フラグを追加します。その日付以降も無効のままにするには、対応する disable フラグを追加します。

Workers runtime でまだサポートされていない Node.js API は、unenv ↗ を使う Wrangler によってポリフィルされます。nodejs_compat compatibility flag が有効で、Worker の compatibility date が 2024-09-23 以降の場合、Wrangler はポリフィルを Worker のコードへ自動注入します。

ポリフィルを追加すると、モックされたメソッドを持つモジュールを提供し、既存の npm パッケージとの互換性が高まります。これらのモックメソッドを呼ぶと、何もしない（noop）か、次のようなメッセージでエラーになります。

[unenv] <method name> is not implemented yet!

一部のメソッドが未サポートでも、これらの Node.js モジュールを使うパッケージを import できます。

Node.js の AsyncLocalStorage API だけを有効にしたい場合は、nodejs_als compatibility flag を有効にします。

{
	"compatibility_flags": ["nodejs_als"],
}

compatibility_flags = [ "nodejs_als" ]