互換性日付

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 が必須になる。

ピンの保証は、インストール済みの wrangler に依存する

compatibility_date はランタイムの挙動を固定するが、その挙動を実装しているコードはローカルにインストールされている wrangler バージョンにバンドルされた workerd の中にある。wrangler dev はピンした日付をそのバンドル済み workerd に対して実行する -- 「この日付時点で Cloudflare のエッジがどう動いていたか」をライブで取得しているわけではない。インストール済みの wrangler が古ければ、ローカル dev は古い workerd が解釈する互換性日付をシミュレートしていることになり、現在の本番エッジが同じピンに対して実際に行っていることと知らないうちにずれる可能性がある。

このピンは一度設定すれば恒久的に保証されるものではなく、実際に再検証したコードパスしか守らない。compatibility_date を変更したときだけでなく、wrangler をアップグレードしたときも wrangler dev（またはプレビューデプロイ）を再実行し、設定ファイルに何の変更もない場合でも定期的に再確認すること。