Workers Caching が適用されないシナリオを先に示し、続けて、すでに使っているほかのキャッシュとの関係を説明します。
キャッシュされるのは GET と HEAD リクエストだけです。POST、PUT、PATCH、DELETE、そのほかのメソッドは、常に Worker を呼び出します。
同じ URL に対する GET と HEAD は、1 つのキャッシュエントリを共有します。キャッシュが空のときに届いた HEAD リクエストは、内部で GET に変換され、完全なアセットでキャッシュが埋まります。キャッシュキー を参照してください。
べき等でないリクエストのレスポンスをキャッシュしたい場合は、Worker 内で明示的に行います。たとえば、リクエスト本文をハッシュして合成 URL を作り、内部の GET サブリクエストを送ります。
WebSocket のアップグレードリクエスト（Upgrade: websocket 付きの GET）はキャッシュを迂回し、常に Worker を呼び出します。WebSocket セッションは定義上ステートフルであり、キャッシュの単位としては向きません。
Workers Caching を通るのは、WorkerEntrypoint に対する fetch() 呼び出しだけです。ctx.exports.Backend.getUser(id) のようなカスタム RPC メソッドはキャッシュを迂回し、エントリポイントの cache.enabled 設定に関係なく、常に呼び出し先を実行します。
いま RPC メソッドとして公開している処理をキャッシュしたい場合は、専用のエントリポイント上の fetch ハンドラーに切り出し、fetch() で呼び出します。
次のレスポンスは、明示的な Cache-Control ディレクティブがあっても、Workers Caching は保存しません。
520–526（Cloudflare のフェイルセーフレスポンス）は一時的なエラーとして扱い、常に Worker を再実行します。- Worker が返す
206 Partial Contentは保存されません。Workers Caching は、Worker が完全な200レスポンスを返し、Range の切り出しは自分で行うことを想定しています。対応しているパターンはRangeリクエスト を参照してください。
Workers Caching が適用されるのは、Worker エントリポイント の fetch ハンドラーが扱う HTTP リクエストだけです。次の呼び出し種別は、キャッシュを介さず常に実行されます。
- Cron Triggers —
scheduledハンドラーによる定期実行。 - Queue コンシューマー —
queueハンドラーで届くメッセージ。 - Workflows — ワークフローステップの実行。
- Tail Workers — トレースイベントのハンドラー。
- Durable Objects — Durable Object の呼び出しは、ハンドラーやメソッドに関係なくキャッシュされません。Durable Object の HTTP レスポンスをキャッシュするには、キャッシュを有効にした Worker エントリポイントの背後に置きます。Durable Object のレスポンスをキャッシュする を参照してください。
「ホスト単位のパージ」モードはありません。キャッシュは ドメインではなく Worker に属します。ホストはキャッシュキーの一部ではないため、ホスト単位のパージはキャッシュが保存しているものに対応しません。代わりに タグ単位のパージ、パスプレフィックス単位のパージ、または purgeEverything を使います。
ビルド時に生成したレスポンスでキャッシュを事前投入する API はありません。レスポンスは、少なくとも 1 回配信されたあとでキャッシュされます。事前レンダリングしたコンテンツを最初のリクエストにも出したい場合は、Static Assets を使います。
レスポンスサイズの制限は、Cloudflare のゾーンキャッシュと同じです。プランごとの制限は キャッシュ可能なサイズ制限 を参照してください。
Cache-Tag 値の個数、長さ、文字種の制限は、Cloudflare のゾーンキャッシュと同じです。一覧は キャッシュタグの制限 を参照してください。
ctx.cache.purge() は、ゾーンのパージ API と同じレート制限システムを使います。ただし Workers Caching はゾーンではなく Worker に紐づくため、アカウントやゾーンのプランに関係なく、常に 可用性と制限 に記載の Free ティアの制限 を使います。
Workers Caching は ゾーンのキャッシュではなく、Worker 自身のキャッシュ です。設定面は Worker そのものなので、横に並べて設定する別レイヤーのルールや設定はありません。次の機能は、いずれも Workers Caching には適用されません。
| ゾーンレベルの機能 | Workers Caching での相当機能 |
|---|---|
| Cache Rules と Cache Response Rules | Worker 内で Cache-Control ヘッダーを設定するか、リクエストに応じて分岐し、パスごとに異なるヘッダーを返します。 |
| Cache Rules でのキャッシュキーのカスタマイズ | Workers Caching には独自のキー構成があります。キャッシュキー を参照してください。リクエストを整形してキーを作ります（たとえば URL を書き換える、ゲートウェイ Worker で ctx.props を設定する）。 |
| ゾーンレベルのキャッシュレベル設定（bypass / standard / aggressive / ignore query string） | レスポンスの Cache-Control ヘッダーで、同じ意図をリクエスト単位で表します。 |
| ゾーンのデフォルトのキャッシュ対象拡張子リスト | Workers Caching は、ヘッダーがキャッシュ可能と示すレスポンスなら、拡張子に関係なくキャッシュします。 |
| カスタムの階層型キャッシュトポロジー | Workers Caching は、デフォルトで汎用の階層型キャッシュトポロジーを使います。Worker はどこでも実行できるため、固定のカスタムトポロジーは当てはまりません。将来 Smart Placement と連携すれば、階層化をさらに調整できる可能性があります。 |
| キャッシュ前にリクエストまたはレスポンスを変更する Rulesets | 返す前に、Worker のコードでリクエストまたはレスポンスを変換します。 |
Worker のキャッシュに影響を与えるには、Worker を変更します。Cache-Control ヘッダー、ctx.props、サービスバインディングの組み合わせ、ctx.cache.purge() が設定面です。
Cache API は、別のプログラム向けキャッシュストアです。Workers Caching とは独立しており、一方の操作は他方に影響しません。Workers Caching のエントリを無効化するのは ctx.cache.purge() です。
新しい Worker では、Workers Caching を優先してください。Cache API は設計上、より低レベルのプリミティブです。
- リードスルーしません。レスポンスがキャッシュされるのは Worker が明示的に
put()を呼んだときだけで、リクエストは入ってくるたびに Worker を実行します。 - 同じリソースへの 同時リクエストの集約 はありません。未キャッシュの URL へのトラフィックのバーストは、リクエストごとに Worker を呼び出します。
- 階層型キャッシュ には参加しません。
Workers Caching は、この 3 つを自動で提供します。細かいプログラム制御が必要なときは、Cache API が役に立ちます。
Workers Caching は、Worker の 手前にある サーバーサイドキャッシュです。Worker が自身のオリジンへ送る fetch() サブリクエストの手前にあるキャッシュとは別物です。両者は独立して動きます。fetch() サブリクエストのヒットはオリジンへの往復を省き、Workers Caching のヒットは Worker 自体の実行を省きます。
Request の cf プロパティは、両者で振る舞いが異なります。
cf プロパティ |
オリジンへの outgoing fetch() |
ctx.exports.<Entrypoint>.fetch() |
|---|---|---|
cf.cacheKey |
対応 | 対応 — カスタムキャッシュキー を参照してください |
cf.cacheControl |
対応 | 対応 — 呼び出し元 Worker から Cache-Control を上書きする を参照してください |
cf.cacheTtl |
対応 | 非対応 — TTL は、呼び出し先から Cache-Control: max-age=N（または s-maxage=N）を返すか、呼び出し元から cf.cacheControl で上書きして設定します |
cf.cacheEverything |
対応 | 非対応 — Workers Caching はレスポンスの Cache-Control からキャッシュ可否を判断します。本来キャッシュできないレスポンスを強制キャッシュする上書きはありません |
次の機能を開発中です。
- Wrangler なしでキャッシュを有効にするための ダッシュボード UI
- Workers Observability の Cache Analytics