互換性日付

Cloudflare の互換性日付の理解と管理

互換性日付とは

wrangler.toml の compatibility_date は Worker を特定バージョンの Cloudflare Workers ランタイムに固定する。これにより破壊的変更がデプロイ済みコードに影響するのを防ぐ。

compatibility_date = "2024-12-01"

仕組み

• Cloudflare は日付に紐づくフラグの背後にランタイム変更を導入する
• 日付を設定するとその日付までのすべての変更が有効になる
• 日付を更新するまで同じランタイム動作を使用する
• 新しいプロジェクトは最近の日付を使用すべき

更新のタイミング

以下の場合に互換性日付を更新する：

• プロジェクトをアクティブに作業中
• 新しいランタイム機能にアクセスしたい場合
• Cloudflare ドキュメントが必要な機能の最低日付を推奨している場合

互換性フラグ

より細かい制御には特定のフラグを有効・無効にできる：

compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

よく使うフラグ：

nodejs_compat が本当に必要になるとき

nodejs_compat は飾りで付けるオプションではない。バンドル（あるいは zfb の _worker.js ラッパーのようなアダプター）が node:async_hooks（AsyncLocalStorage）、node:crypto、node:buffer といった Node.js 組み込みモジュールを import している場合、このフラグを省略すると wrangler は worker のロードを拒否する。これは デプロイ時の失敗であり、ランタイムでの穏やかなフォールバックではない — デプロイが止まるだけで、こっそり機能を落として動く worker が手に入るわけではない。

compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

具体的なトリガーは、SSR バインディングアダプターのレシピで使われる AsyncLocalStorage のリクエスト単位コンテキストパターンだ。これは node:async_hooks を介して Cloudflare のバインディング（KV、D1、R2、env）を getCloudflareContext() 形式のアクセサーへ受け渡す。この import がバンドルに入った瞬間、その worker のすべてのデプロイで nodejs_compat が必須になる。