Node.jsの互換性

Workerを作成する際、npm ↗からパッケージをインポートする必要がある場合があります。多くのnpmパッケージはNode.jsランタイム ↗のAPIに依存しており、これらのNode.js APIが利用可能でないと動作しません。

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

1. Workersランタイムによって提供される組み込みAPI
2. WranglerがあなたのWorkerのコードに追加するポリフィル

どのAPIがサポートされているかは、Node.js互換性マトリックス ↗を使用して確認できます。

始める

Workerのために組み込みランタイムAPIとポリフィルの両方を有効にするには、wrangler.tomlにnodejs_compat_v2 互換性フラグを追加します：

wrangler.toml

compatibility_flags = [ "nodejs_compat_v2" ]

組み込みランタイムAPIのみを有効にするには、wrangler.tomlにnodejs_compat 互換性フラグを追加します：

wrangler.toml

compatibility_flags = [ "nodejs_compat" ]

ノート

2024年9月23日以降、互換性日が2024-09-23以降の場合、nodejs_compat互換性フラグはnodejs_compat_v2と同じ動作を有効にします。

組み込みNode.jsランタイムAPI

以下のNode.js APIは、Workersランタイムによって直接提供されます。これらはnodejs_compatまたはnodejs_compat_v2を使用する際に利用可能です：

• assert
• AsyncLocalStorage
• EventEmitter
• StringDecoder
• util
• ストリーム
• テスト
• パス
• バッファ
• プロセス
• 暗号
• 診断チャネル

Node.js APIはnode:プレフィックスの下で利用可能であり、このプレフィックスはモジュールをインポートする際に、あなたのコードや依存するnpmパッケージの両方で使用する必要があります。

// これを行います：
import { Buffer } from "node:buffer";

// これを行ってはいけません：
import { Buffer } from "buffer";

特に指定がない限り、WorkersにおけるNode.js APIの実装はNode.jsの現在のリリース ↗の実装に一致することを意図しています。

Node.js APIポリフィル

nodejs_compat_v2互換性フラグを使用する際、WorkersランタイムでNode.js APIを有効にするだけでなく、Wranglerはunenv ↗を使用してNode.js APIの使用を自動的に検出し、関連するポリフィルを追加します。

ポリフィルを追加することで、既存のnpmパッケージとの互換性が最大化されますが、すべてのNode.js APIがサーバーレス関数の文脈で意味を持つわけではないことを認識しています。

関連するNode.js APIの完全な機能的ポリフィルを提供することが可能な場合、unenvはそれを行います。 これが不可能な場合、例えばfs ↗のように、unenvはモックメソッドを持つモジュールを追加します。 これらのモックメソッドを呼び出すと、何も行わないか、次のようなメッセージでエラーがスローされます：

[unenv] <method name> はまだ実装されていません！

これにより、特定のメソッドがサポートされていなくても、これらのNode.jsモジュールを使用するパッケージをインポートすることができます。

サポートされているAPIの完全なリスト、モックされているものに関する情報については、Node.js互換性マトリックス ↗を参照してください。

WorkersでNode.jsを有効にする

wrangler.tomlにnodejs_compat 互換性フラグを追加します：

wrangler.toml

compatibility_flags = [ "nodejs_compat_v2" ]

Pages FunctionsでNode.jsを有効にする

WranglerでPagesにNode.jsを有効にする

ローカル開発でnodejs_compatを有効にするには、wrangler pages devにnodejs_compatフラグを持つ--compatibility-flags引数を渡します：

npx wrangler pages dev [<DIRECTORY>] --compatibility-flags="nodejs_compat"

追加のオプションについては、Pages特有のCLIコマンド ↗のリストを参照してください。

CloudflareダッシュボードからPagesでNode.jsを有効にする

CloudflareダッシュボードからPages FunctionにNode.jsを有効にするには：

1. Cloudflareダッシュボード ↗にログインし、アカウントを選択します。
2. Workers & Pagesを選択し、概要でPagesプロジェクトを選択します。
3. 設定 > 関数 > 互換性フラグを選択します。
4. プレビューおよび本番デプロイメントにnodejs_compat_v2互換性フラグを追加します。

AsyncLocalStorageのみを有効にする

Node.jsのAsyncLocalStorage APIのみを有効にするには、nodejs_als互換性フラグを使用します。

compatibility_flags = [ "nodejs_als" ]

関連リソース

• 最適化された体験のために、ESモジュール構文でWorkerコードを書く。