Cloudflare WorkersのNode.js互換性とは｜2026年8月の既定化を初心者向けに解説

この記事でわかること

• Cloudflare WorkersのNode.js互換性が何を助ける機能なのか
• 2026年8月4日以降のcompatibility_dateで何が変わるのか
• nodejs_compatとnodejs_compat_v2を新規設定に書かなくてよいケース
• 既存プロジェクトでcompatibility_dateを上げる前に確認すること
• Wrangler設定例を読むときの基本ポイント

結論・重要ポイント

1. Cloudflare Workersでは、2026年8月4日以降のcompatibility_dateからNode.js互換性が既定で有効になります。
2. 新しいcompatibility_dateでは、nodejs_compatやnodejs_compat_v2を追加しなくても、対応済みのNode.js APIやポリフィルが使える扱いになります。
3. 既存プロジェクトの古いcompatibility_dateには、自動では影響しません。
4. compatibility_dateを更新すると、Node.js互換性以外の互換性変更も同時に入る可能性があります。
5. 本番反映前に、依存パッケージ、設定ファイル、ローカル動作、ステージング環境を確認するのが安全です。

対象読者と前提知識

この記事は、Cloudflare WorkersやWranglerを使い始めたばかりで、compatibility_dateやnodejs_compatという設定名に不安がある初学者向けです。

前提知識は、JavaScriptのファイルをデプロイしてWeb上で動かす仕組みがある、という理解で問題ありません。この記事では課金設定、秘密情報、実際の本番デプロイ操作は扱いません。設定の意味と確認手順に絞って説明します。

3人による授業形式の会話

コード・操作手順・具体例

1. 新しいcompatibility_dateの設定例

Cloudflareの公式資料では、compatibility_dateはWorkerの互換性変更を選ぶ日付として説明されています。2026年8月4日以降の日付を使うと、Node.js互換性が既定で有効になる扱いです。

wrangler.jsoncの設定例です。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-08-04"
}

この例では、compatibility_flagsにnodejs_compatを追加していません。新規プロジェクトでは、まず公式資料の推奨に合わせて、余計なフラグを書かない形を検討します。

2. 古いcompatibility_dateで明示的に有効化する例

2026年8月4日より前のcompatibility_dateを使う場合は、nodejs_compatを明示する形があります。

wrangler.tomlの設定例です。

name = "my-worker"
main = "src/index.js"
compatibility_date = "2026-08-03"
compatibility_flags = ["nodejs_compat"]

この設定は、古い互換性日付を使いながらNode.js互換性を有効にしたい場合の考え方です。既存プロジェクトでは、日付を上げる方がよいのか、フラグで対応する方がよいのかを、テスト結果と合わせて判断します。

3. Node.jsモジュールを読む例

Workersで対応しているNode.js APIの範囲では、**node:**から始まるモジュールを使える場合があります。

JavaScriptの例です。

import { Buffer } from "node:buffer";

export default {
  async fetch() {
    const value = Buffer.from("hello workers").toString("base64");
    return new Response(value);
  }
};

この例は、node:bufferを使う書き方を示しています。ただし、この記事内では実際にプロジェクトへデプロイしていないため、「動作確認済み」とは記載しません。利用前には公式のNode.js互換性資料と、手元のWorkers環境で確認してください。

4. Node.js互換性を明示的に無効化する例

2026年8月4日以降のcompatibility_dateでも、Node.js互換性を完全に無効化したい場合は、Cloudflare公式資料では無効化フラグを使う形が示されています。

wrangler.tomlの例です。

name = "my-worker"
main = "src/index.js"
compatibility_date = "2026-08-04"
compatibility_flags = ["no_nodejs_compat", "no_nodejs_compat_v2"]

この設定は、Node.js互換性を使わせたくない理由が明確な場合だけ検討します。既存の依存パッケージがNode.js APIを前提にしていると動かなくなる可能性があるため、変更前後でテストしてください。

5. 既存プロジェクトで確認する順番

既存プロジェクトでは、次の順番で見ると混乱しにくくなります。

1. wrangler.jsonc または wrangler.toml を開く
2. compatibility_date の日付を確認する
3. compatibility_flags に nodejs_compat 系があるか確認する
4. 使っているnpmパッケージがNode.js APIを必要としているか確認する
5. ローカル実行とテストを行う
6. ステージング環境など本番以外で確認する
7. 問題がなければ本番反映の手順を決める

※本番反映、削除、上書き、課金や公開範囲に関わる操作は、必ずプロジェクトの運用ルールに合わせて確認してから実行してください。

よくある誤解や失敗

誤解1. WorkersがNode.jsそのものになる

Node.js互換性は、WorkersでNode.js由来のAPIやパッケージを使いやすくするための仕組みです。Node.jsサーバーの全機能がそのまま同じ意味で動く、と考えるのは危険です。

誤解2. 既存プロジェクトも自動で変わる

Cloudflare Workersの互換性変更は、基本的にcompatibility_dateで選びます。古い日付の既存Workerが、何もしていないのに急に新しい挙動へ切り替わる、という理解ではありません。

誤解3. nodejs_compatをすぐ削除してよい

新しい日付では正のフラグが不要になるケースがありますが、既存設定を整理するならテストと差分確認が先です。設定を減らすことより、動作が変わらないことの確認を優先します。

誤解4. npmパッケージなら何でも使える

対応APIは増えていますが、パッケージがファイルシステム、プロセス、ネットワーク、ネイティブ拡張などに強く依存している場合は注意が必要です。公式の対応APIとエラー内容を確認してください。

Q&A

Q. 新規Workerではnodejs_compatを書かなくてよいのですか？

compatibility_dateが2026年8月4日以降なら、公式資料ではnodejs_compatとnodejs_compat_v2が既定で有効になると説明されています。新規設定では、まずフラグなしで考えるのが自然です。

Q. 既存Workerのcompatibility_dateを今日の日付に上げるべきですか？

必ず上げるべき、とは言えません。新機能を使いたい場合や設定を整理したい場合は候補になりますが、互換性変更の影響を確認してから進めます。

Q. nodejs_compat_v2はもう不要ですか？

2026年8月4日以降のcompatibility_dateでは、正のフラグは使われない扱いと説明されています。ただし、古い日付の既存プロジェクトでは意味が変わるため、設定全体を見て判断します。

Q. エラーが出たら最初に何を見ればよいですか？

まずcompatibility_date、compatibility_flags、Wranglerのバージョン、使っているnpmパッケージ、エラーメッセージを確認します。次に、公式のNode.js互換性資料で、そのAPIがWorkersでどの扱いになっているかを見ます。

要点まとめ

• 2026年8月4日以降のcompatibility_dateでは、WorkersのNode.js互換性が既定で有効になります。
• 新規プロジェクトでは、nodejs_compatを書かずに始められるケースがあります。
• 既存プロジェクトでは、日付やフラグを変える前にテストします。
• Node.js互換性は便利ですが、Node.jsサーバーと完全に同じではありません。
• 設定を変えるときは、公式資料、ローカル確認、ステージング確認の順で進めると安全です。

公式資料・参考資料

• Cloudflare Changelog: Node.js compatibility is now enabled by default
• Cloudflare Workers Docs: Compatibility flags
• Cloudflare Workers Docs: Compatibility dates
• Cloudflare Workers Docs: Wrangler configuration
• Cloudflare Workers Docs: Runtime APIs

授業に登場する3人については、MAO先生のIT授業 キャラクター紹介で確認できます。

Cloudflare WorkersやWebアプリ設定で迷ったら

compatibility_date、Wrangler設定、npmパッケージ、デプロイ前の確認手順は、プロジェクトごとに判断が変わります。

MAO工房では、小規模事業者様向けのWebアプリ開発や運用相談で、設定ファイルの読み解き、更新前の確認、公開前の安全チェックまで一緒に整理できます。

• WorkersやWebアプリの設定を見直したい
• 依存パッケージ更新や互換性変更が不安
• 本番反映前の確認手順を作りたい

必要な範囲を小さく確認しながら進めたい場合は、お問い合わせからご相談ください。