Zenn
📝

Workers の Cache API・Fetch API と Cache rules どっちが優先？（デフォルト挙動の変更に注意）

に公開
Cloudflare
cache
Cloudflare Workers
tech

はじめに

Cloudflare Cache rules のキャッシュバイパス条件にマッチするリクエスト（あるいは Development mode 適用時）は Workers の Fetch API や Cache API でキャッシュする設定になっていても、 Cache rules に従いバイパスされていました。
この動きについて、 2025 年 4 月 2 日から Workers の設定を優先にできそうなので、試します。

For example, if there is a cache rule configured to bypass cache for example.com/foo, but your Workers script sets cacheEverything: true, the script's setting will take precedence, and the request will be cached. The same applies if the request is made to a non-Cloudflare zone — the Worker's cacheEverything setting will still override.

概要

優先度

Workers と各ルールの優先順は以下ということで、Workers が一番強くなります。

  1. Workers script settings
  2. Cache rules
  3. Page rules

設定

ただ、この順にする方法は Workers スクリプトの Compatibility dates によって変わってきます。
具体的にはスクリプトの Compatibility flags で制御します。

デフォルト設定と上書き

執筆時点（2025 年 5 月）では以下の様相です。

Compatibilitiy dates request_cf_overrides_cache_rules cache_api_request_cf_overrides_cache_rules
2025-04-01 以前 デフォルト 無効
flag 追加で有効 		N/A
flag を追加しても動作に影響ないように見える
2025-04-02 以降 デフォルト 有効 〃
2025-04-19 以降 〃 デフォルト 無効
flag 追加で有効
執筆時点では Devdocs の記載を見つけられず
2025-05-19 以降 〃 デフォルト 有効
執筆時点では Devdocs の記載を見つけられず

動作確認（Compatibility date ごと）

以下を前提に動作を確認します。

項目 設定 備考
Cache rules Bypass Cache devdocs
Workers
Fetch API		 fetch(request,{cf:{cacheEveryting: true}}) devdocs
Workers
Cache API		 caches.default.match, caches.default.put devdocs

Cache rules
対象ホストごとバイパスしています。

Workers スクリプト
こちらを元に Fetch API でキャッシュするよう追記しました。

変更部分（Fetch API でキャッシュ指定に変更。Cache API はそのまま）
var CACHE_DURATION_SECONDS = 10;
:
response = await fetch(request, { cf: { cacheEverything: true, cacheTtl: 60 } });
:

以下、Compatibility dates ごとに確認します。

2025-04-01 以前

デフォルト（Compatibility flags なし）

リクエストを送信し、結果を Instant logs で確認します。
（Free や Pro では Instant logs を確認できませんが、同じようなことが内部で起こっています。）

フローにするとこんな感じ（正確ではありません）。

  • Workers Cache API
    match・put どちらのリクエストも Cache rules の設定に従い、拒否（バイパス）されています。

  • Workers Fetch API
    詳細を見ると CacheCacheStatus が dynamic で、こちらも Cache rules でバイパスされていることがわかります。

  • Eyeball への応答
    結果、元のリクエストに対して dynamic でバイパスされたレスポンスが戻されています。

Compatibility flags 追加

Compatibility flags を立ててみます。

執筆時点では、前者はセレクターに現れましたが、後者は現れずでした。コピペで入りました。

リクエストを送信します。

  • Workers Cache API
    変わりません。バイパスが優先され、拒否されています。
  • Workers Fetch API
    キャッシュが効くようになりました。
  • Eyeball への応答
    元リクエストに対するレスポンスはデフォルト時の dynamic から miss に変わり、 Fetch API がキャッシュ対象になったことがわかります。

    後続のリクエストをみると、相変わらず Cache API では拒否されますが、

    hit でキャッシュからサーブされています。

結果

  • Workers Fetch API
    Compatibility flags を立てることで、挙動が変わり Cache rules を上書き
  • Workers Cache API
    Compatibility flags を立てても Cache rules 優先（バイパス）

2025-04-02 から 2025-04-18

デフォルト（Compatibility flags なし）

リクエストを送信します。

相変わらず Cache API は拒否されていますが、レスポンスが revalidated で Fetch API がキャッシュ対象になっていることがわかります。
（一つ前のケースのキャッシュが残っていたため miss でなく revalidated となりました）

後続のリクエストは期待通り hit になります。

デフォルトで request_cf_overrides_cache_rules が有効になったことがわかります。

設定しようとすると怒られる

デフォルトで有効となった flag を有効にしていると、デプロイできません。

Compatibility flags 追加

Cache API 上書きのために、Compatibility flags を立てます。

動作は変わりません。

結果

  • Workers Fetch API
    デフォルトで Cache rules を上書き
  • Workers Cache API
    Compatibility flags を立てても Cache rules 優先（バイパス）

2025-04-19 から 2025-05-18

デフォルト（Compatibility flags なし）

2025-04-02 と同じです。

Compatibility flags 追加

Compatibility flags の設定が効き、Cache API も優先になることが確認できました。

一回目のリクエストで Cache API put（PUT）ログ ＝ 204 扱いで成功したことがわかります。

後続のリクエストは Cache API match（GET）ログ ＝ 200 扱いでこちらも成功しています。

結果

  • Workers Fetch API
    デフォルトで Cache rules を上書き
  • Workers Cache API
    Compatibility flags を立てることで Cache rules を上書き

2025-05-19 以降

デフォルト（Compatibility flags なし）

デフォルトでどちらも Cache rules を上書きします。

後続のリクエストは Cache API で得ることができ、一つ前のケースと同様に hit となりました。

Compatibility flags 追加

Cache rules を上書きするのに Compatibility frags を追加する必要はなくなりました。

設定しようとすると怒られる
wrangler.toml
name = "cache-api-test-new"
main = "src/worker.js"
workers_dev = true
compatibility_date = "2025-05-19"
compatibility_flags = [ "cache_api_request_cf_overrides_cache_rules" ]
#compatibility_flags = [ "request_cf_overrides_cache_rules", "cache_api_request_cf_overrides_cache_rules" ]
:
npx wrangler deploy
  : 
  The compatibility flag cache_api_request_cf_overrides_cache_rules became the default as of
  2025-05-19 so does not need to be specified anymore.
   [code: 10021]
  :

結果

  • Workers Fetch API
    デフォルトで Cache rules を上書き
  • Workers Cache API
    デフォルトで Cache rules を上書き

2025-04-02 より前のデフォルトに合わせる

逆に、以前のデフォルトに合わせるケースがでてきます。
no_ 接頭詞をつけたフラグを付けることで、デフォルト変更前の動きを継続することができます。

wrangler.toml
name = "cache-api-test-new"
main = "src/worker.js"
workers_dev = true
compatibility_date = "2025-05-19"
compatibility_flags = [ "no_request_cf_overrides_cache_rules", "no_cache_api_request_cf_overrides_cache_rules" ]
:

Snippets はどうか

Snippets の場合は 2025-04-01 以前の動き（常に Cache rules のバイパスが優先）のようでした。
ただ Devdocs の記載を見つけられていないので、不明です。
参考まで。

まとめ

Cache rules バイパスの設定を Workers の Fetch API、Cache API のどちらであっても上書きしキャッシュしたい場合は

Compatibility dates 2025-05-19 以降

がよさそうです。

また、既存のスクリプトを移植するような場合は Compatibility dates とデフォルトの挙動を気にする必要があるでしょう。

参考

https://developers.cloudflare.com/workers/reference/how-the-cache-works/
https://developers.cloudflare.com/cache/interaction-cloudflare-products/workers-cache-rules/

Discussion