Cloudflare は Workers ランタイムを定期的に更新しています。これらの更新はすべての Worker にグローバルに適用され、すでにデプロイ済みの Worker が動作しなくなることはありません。ただし、後方互換性のない変更が入ることがあります。特に、既存の Worker が意図せず依存しているランタイム API のバグがある場合があります。Cloudflare はバグ修正を実装し、新しい Worker はオプトインできます。既存の Worker は、デプロイ済みの Worker を壊さないよう、従来の（バグのある）動作のままです。
互換性日付とフラグは、こうしたランタイムの変更を開発者としてオプトインする仕組みです。互換性フラグ には、デフォルトで有効になる日付が付いていることが多く、Worker に compatibility_date を指定すると、その日付までに有効になる各種互換性フラグをまとめて有効にできます。
プロジェクトを始めるときは、常に compatibility_date を当日の日付に設定してください。compatibility_date フィールドは、ときどき更新します。更新するときは、互換性フラグ のページで変更内容を確認し、Worker をテストして影響があるかを確かめ、必要に応じてコードを更新してください。新しい互換性日付は、次に npx wrangler deploy を実行したときに有効になります。
更新したくない場合は、compatibility_date を変更する必要はありません。Workers ランタイムは、古い互換性日付を永続的にサポートします。やむを得ず稼働中の Worker を壊す変更が必要な場合、Cloudflare は影響を受ける開発者に連絡します。ただし、Cloudflare はそのような変更をできるだけ避けます。
それでも、compatibility_date フィールドを更新する必要はなくても、次の 2 つの理由から更新することを推奨します。
- 新しい機能は、最新の
compatibility_dateを持つ Worker にだけ提供されることがあります。最新機能を使うには、日付を更新してください。 - 一般に、互換性フラグ のページ以外では、Workers のドキュメントは現行の
compatibility_dateの動作だけを説明し、過去の動作は省略することがあります。古いcompatibility_dateを使う Worker では、使っている API に変更がないかを確認するため、互換性フラグのページを継続的に参照する必要があります。
互換性日付は、Worker の Wrangler 設定ファイル で設定できます。
{
// Opt into backwards-incompatible changes through April 5, 2022.
"compatibility_date": "2022-04-05"
}compatibility_date = "2022-04-05"Cloudflare ダッシュボードで Worker を作成すると、互換性日付は自動的に当日の日付に設定されます。
互換性日付は、Cloudflare ダッシュボード ↗ の Workers 設定で更新できます。
互換性日付は、Workers Script API または Workers Versions API で Worker をアップロードするときに、リクエスト本文の metadata フィールドで設定できます。
API 経由のアップロードで互換性日付を指定しない場合、フラグが有効になる前の最も古い互換性日付（2021-11-02）がデフォルトになります。API で新しい Worker を作成するときは、互換性日付を当日の日付に設定することを強く推奨します。