Workers Cache
Workers Cache (blog.cloudflare.com)
要約
Cloudflareは、Workerの前に配置される新しいキャッシュ機能「Workers Cache」を発表しました。これにより、WorkerのCPU時間を節約し、サーバーサイドレンダリングされたアプリケーションのパフォーマンスを大幅に向上させることができます。この機能は、標準的なHTTPキャッシュヘッダーと`stale-while-revalidate`ディレクティブを活用し、開発者がコードでキャッシュを簡単に設定・管理できるようにします。
全文翻訳
Your Worker can now have its own cache in front of it
本日、CloudflareはWorkers Cacheをローンチしました。これは、Wranglerの設定1行と、すでに使い慣れているCache-Controlヘッダーで構成される、あなたのWorkerの前に配置される階層型キャッシュです。
Workers Cacheが有効になっている場合、あなたのWorkerへのキャッシュ可能なリクエストはすべて、まずCloudflareのキャッシュにヒットします。新鮮なキャッシュ済みレスポンスがあれば、Cloudflareはそれを直接返します。あなたのWorkerは実行されず、CPU時間もかかりません。キャッシュミスの場合、Workerが実行され、レスポンスがキャッシュ可能であれば、Cloudflareはそれを次回の要求のために保存します。地球上のどこからの次のリクエストも、キャッシュから直接提供されます。
[画像: BLOG-3262 image1]
すべては1つの設定ブロックで完結します。
{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2026-05-01",
"cache": {
"enabled": true
}
}
その後、HTTPが常に望んでいた方法、つまりレスポンスにヘッダーを設定することで、キャッシュを制御します。
return new Response(body, {
headers: {
"Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
"Cache-Tag": "products,product:123",
},
});
コンテンツが変更されたら、Workerは独自のキャッシュをパージします。
await ctx.cache.purge({ tags: ["product:123"] });
これがAPIのすべてです。ゾーンの設定、ルールの設定、プロビジョニングする別のキャッシュ、ログインする別の製品はありません。Workerのコードが設定面であり、キャッシュはカスタムドメイン、workers.dev、サービスバインディングの後ろ、プレビュー、Workers for Platformsテナントなど、Workerが実行される場所ならどこにでも追従します。1つのWorker、1つのキャッシュ、一度設定すれば完了です。
これが表面的な部分です。その下には多くのものがあります。ネットワーク全体にわたる階層型キャッシュ、ユーザーをブロックしない古いレスポンスを提供するstale-while-revalidateの完全サポート、Varyによるコンテンツネゴシエーション、ctx.propsによるマルチテナントセーフなキャッシュキー、タグまたはパスプレフィックスによるプログラムによるパージ、そして最も大きなアンロックになると考えている部分――公開されているものだけでなく、すべてのWorkerエントリポイントの前に配置され、どのエントリポイントがキャッシュするかしないかの制御がエントリポイントごとに行えるキャッシュです。この最後の部分は、キャッシュをアプリの構造に直接組み込むことができることを意味します。キャッシュステージを好きな場所に配置したエントリポイントのチェーンを構築できます。これは、両側のコードによって構成されます。以下でそのすべてを説明します。
Workers Cacheは、Wranglerで有効にすれば、すべてのプランのすべてのWorkerで今日から利用可能です。
これは、私たちが常にWorkersに持たせたかったキャッシュAPIです。なぜこれほど時間がかかったのか、それによって何が可能になるのか、そして次に何が来るのかを見てみましょう。
サーバーレンダリングアプリが前にキャッシュを必要とする理由
私たちが2017年にWorkersを発表したとき、Cloudflareのネットワーク上でコードを実行して、オリジンへのリクエストを変換できるというものでした。Workerはキャッシュとオリジンの前に配置されていました。
[画像: BLOG-3262 image5]
これは、私たちがターゲットとしていたユースケースにとって正しいモデルでした。すべてリクエストにヘッダーを追加したい、URLを書き換えたい、A/Bテストを行いたい、またはオリジンに到達する前にトラフィックをフィルタリングしたい場合、Workerをキャッシュとオリジンの前に置くことで、何がキャッシュされ、何がキャッシュされないかを完全に制御できました。顧客はそれを使って信じられないようなものを作り上げました。
しかし、世界は変わりました。Workersはオリジンに追加するものではなくなり、オリジンそのものになりました。Astro、TanStack Start、Next.js、Remix、SvelteKitのようなフレームワークはすべてCloudflareアダプターをシップしており、あなたのアプリをWorkerとしてビルドします。それらの後ろにオリジンはありません。Workerがサーバーなのです。
Workerがオリジンである場合、元のアーキテクチャにはキャッシュするものがありません。レスポンスが1秒前に返したレスポンスとバイト単位で同一であっても、すべてリクエストでコードが実行されます。Workersランタイムは十分に高速なのでこれは機能します。数十億リクエスト/秒を問題なく処理していますが、「すべてのリクエストをレンダリングするのに十分な速度」でも、ページロードごとのレイテンシと呼び出しごとのCPU時間がかかります。そしてサーバーレンダリングアプリでは、すべてのページロードは定義上レンダリングです。
Workers Cacheはアーキテクチャを反転させます。CloudflareのキャッシュがWorkerの前に配置されます。
[画像: BLOG-3262 image9]
キャッシュヒットの場合、Workerはまったく実行されません。Cloudflareはキャッシュされたレスポンスを返し、CPU課金はゼロのままです。ミスの場合、Workerは一度実行され、キャッシュを埋め込み、次のリクエスト(どこからでも)はコードを呼び出さずにキャッシュから提供されます。
これがWorkersでのサーバーサイドレンダリングに欠けていたものです。以前は、2つの満足のいかない選択肢から選ぶ必要がありました。
- ビルド時にすべてを事前レンダリング(「静的サイト生成」)。高速なページロードですが、すべての変更には完全な再ビルドと再デプロイが必要です。数千ページあるドキュメントサイトでは、5〜10分かかります。大規模なeコマースサイトではさらに悪化します。そして、何かを変更するたびにビルドが実行されます。
- すべてのリクエストで各ページをレンダリング。最新のコンテンツですが、すべてのページロードでレンダリングコストがかかり、すべての訪問者がレイテンシを支払います。
Workers Cacheは3番目の選択肢を提供します:オンデマンドでサーバーレンダリングし、レンダリングされたレスポンスをキャッシュし、あなたが選択したTTL(Time To Live)でそれを更新します。新しいページの最初の要求は依然としてレンダリングされます。キャッシュが期限切れになるまでの後続のすべての要求は、ページが静的であるかのように提供されます。キャッシュが期限切れになると、次の要求が再レンダリングをトリガーします。stale-while-revalidateを使用すれば、それすら待つ必要がありません。
ビルド時間なしでサーバーレンダリングの速度を得られ、コストなしでサーバーレンダリングの鮮度を得られます。Incremental Static Regenerationのようなフレームワーク固有の仕組みは不要です。単にHTTPキャッシュが、オリジンとして設計されたコードの前に、設計通りに機能するだけです。
stale-while-revalidateは瞬時に感じさせる部分です
stale-while-revalidateディレクティブは、キャッシュされたレスポンスの有効期限が切れたときに、Cloudflareが即座に古いコピーを提供することを許可し、バックグラウンドでレスポンスをリフレッシュすることをCloudflareに伝えます。Cloudflareは今年初めにstale-while-revalidateの完全サポートをリリースしました。そして、これは「Workerをキャッシュする」を「Workerのサイトが静的であるかのように感じさせる」ものに変えるディレクティブです。
これがない場合、キャッシュエントリの有効期限が切れた後の最初の要求は、Workerがページをゼロからレンダリングするのを待つ必要があります。ユーザーはそのレイテンシを見ます。これがある場合、有効期限切れ後の最初の要求は即座に古いページを取得し(Cf-Cache-Status: UPDATINGヘッダー付き)、Workerはバックグラウンドで実行されてキャッシュを補充します。リフレッシュをトリガーしたユーザーを含むすべてのユーザーが、キャッシュ速度のレスポンスを受け取ります。
[画像: BLOG-3262 image3]
実際には、これは次のように見えます。
export default {
async fetch(request) {
const html = await renderPage(request);
return new Response(html, {
headers: {
"Content-Type": "text/html; charset=utf-8",
// 5分間は新鮮として扱い、バックグラウンドリフレッシュ中に
// 最大1時間古いものを提供します。
"Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
},
});
},
};
これが理解できるメンタルモデルです。
- 新鮮なウィンドウ (
max-age):Cloudflareはキャッシュされたレスポンスを提供します。あなたのWorkerは実行されません。 - 古いウィンドウ (
stale-while-revalidate):Cloudflareはキャッシュされたレスポンスを提供します。あなたのWorkerはバックグラウンドでそれをリフレッシュするために実行されます。ユーザーは待ちません。 - 両方のウィンドウの外側:CloudflareはWorkerを実行して新鮮なレスポンスを生成し、ユーザーはそのレンダリングを待ちます。
ウィンドウを選択します。数分ごとに更新される商品カタログの場合、max-age=300、stale-while-revalidate=3600は、訪問者が基本的に待つことはなく、Workerはコンテンツを新鮮に保つのに十分な頻度で実行されることを意味します。ほとんど変更されないブログアーカイブの場合、max-age=86400、stale-while-revalidate=2592000は、ページごとにWorkerが1日1回実行されることを意味します。
ブランドニューページの最初の要求だけが、完全なレンダリングコストを支払います。その後、ページは訪問者にとって静的出力のように動作しますが、Workerはページの生成方法を所有し続けます。
1つのURL、複数の表現:Varyが機能する
実際のアプリは、すべてのクライアントに同じバイトを返すことはめったにありません。同じ商品ページは、ブラウザ向けにはHTML、APIクライアント向けにはJSONかもしれません。同じ画像は、それをサポートするクライアントにはWebP、サポートしないクライアントにはJPEGかもしれません。同じホームページは、ユーザーに応じて、英語、フランス語、または日本語で返されるかもしれません。
キャッシュなしでこれを実行するのは簡単です。Workerはリクエストヘッダーを読み取り、正しいものを返します。キャッシュありでこれを実行するのは、通常、醜くなります。ほとんどのキャッシュは、2つの悪い選択肢を提供します。複数の表現を持つURLでは何もキャッシュしないか、1つの表現をキャッシュして全員に提供するかです。
Workers Cacheは標準のHTTP Varyヘッダーをサポートしており、これはこの問題を解決する正しい方法です。WorkerがVary: Accept-Encoding(またはAccept、Accept-Language、その他のリクエストヘッダー)を持つレスポンスを返すと、Cloudflareはそれらのヘッダーの各異なる組み合わせに対して個別のキャッシュバリアントを保存し、保存された値が着信リクエストと一致するバリアントのみを返します。
export default {
async fetch(request) {
const accept = request.headers.get("Accept") ?? "";
const wantsWebp = accept.includes("image/webp");
const body = wantsWebp ? await fetchWebpImage() : await fetchJpegImage();
return new Response(body, {
headers: {
"Content-Type": wantsWebp ? "image/webp" : "image/jpeg",
"Cache-Control": "public, max-age=3600",
// Varyヘッダーの値ごとに個別のバリアントをキャッシュします。
Vary: "Accept",
},
});
},
};
1つのURL、2つのキャッシュバリアント。Accept: image/webp,*/*を送信するブラウザはWebPを取得します。Accept: image/jpegを送信するブラウザはJPEGを取得します。どちらもキャッシュから提供されます。Workerはそれぞれ最初の要求で両方のバリアントを書き込み、その後はどちらもゼロ回実行されません。
これはコンテンツネゴシエーションのための確立されたHTTP標準であり、Workers CacheはRFC 9110とRFC 9111が説明する方法でそれを実装しています。Varyできるヘッダーの許可リストはありません。必要なものをリストアップすれば、Cloudflareは正確な値でバリアントをキー付けします。ドキュメントでは、エッジケース(ゲートウェイWorkerでヘッダーを正規化してバリアントのファンアウトを制御する方法、パージがURLのすべてのバリアントをまとめて無効にする理由、およびキャッシングを完全に無効にする1つのケース(Vary: *)を説明しています。
これはあなたのゾーンのキャッシュではなく、あなたのWorkerのキャッシュです
これらすべてで何が可能になるかに入る前に、名前を付ける価値のある概念的なシフトがあります。
Cloudflareは何年もキャッシュを持っていました。それはゾーンレベルで構成されます:Cache Rules、Page Rules、キャッシュファイル拡張子のリスト、Cache Reserve、Tiered Cacheトポロジー、カスタムキャッシュキー。すべてゾーンごとに設定され、歴史的にWorkerはゾーンの設定に適合するか、それを回避する必要がありました。
Workers Cacheは異なります。それはあなたのWorkerのキャッシュであり、ゾーンではなくWorkerに属します。これは、実際に重要な多くの結果をもたらします。
- 管理するゾーン設定はありません。Cache Rules、キャッシュレベル設定、ファイル拡張子リスト、Page Rulesは、Workers Cacheには適用されません。Workerの
Cache-Controlヘッダーが設定です。 - キャッシュはホスト名ではなくWorkerに追従します。
api.example.com、api.example.netにバインドされ、サービスバインディング経由で呼び出されるWorkerは、3つすべてで1つのキャッシュを共有します。/users/42へのリクエストは、どの経路で入ってきたかに関わらず、同じキャッシュエントリにヒットします。 - キャッシュは
workers.devで機能します。プレビューURLでも機能します(各プレビューは独自のキャッシュを持つため、変更のテストが本番環境を損なうことはありません)。Workers for Platformsでも機能します(各ユーザーWorkerは、ディスパッチャーや他のテナントから分離された独自のキャッシュを持ちます)。これらはすべて、以前はキャッシュにとって二級市民でした。もうそうではありません。 - パージはWorkerのエントリポイントにスコープされます。
ctx.cache.purge({ purgeEverything: true })を呼び出すと、Workerエントリポイントのキャッシュのみがパージされます。ゾーンの他のコンテンツを削除するリスクはありません。あるWorkerのデプロイが別のWorkerのデータを無効にするリスクもありません。
キャッシュについて構成することは、コード内で構成します。どのパスがより長いTTLを持つか(パスで分岐して異なるmax-ageを設定する)、どのリクエストがキャッシュをバイパスするか(Cache-Control: privateを返す)、キャッシュキーがどのように形成されるか(ctx.propsに何が含まれるかを制御する、ディスパッチする前にゲートウェイWorkerでURLを正規化する)。すでに書いたWorkerが設定面です。
ドキュメント全体で、Workers Cache: your Worker's cacheで詳細に説明しています。
2つのティア、すべてのWorker、設定不要
Workers Cacheはデフォルトでリージョン階層化されています。2つのレイヤーがあります。
- 下位ティア:ユーザーに最も近いCloudflareデータセンターにあります。あなたのWorkerのトラフィックを受け取るすべてのデータセンターには、独自の低位ティアキャッシュがあります。
- 上位ティア:ネットワーク全体からのフィルを統合します。これらは少なく、すべての低位ティアはミス時に上位ティアを参照します。
リクエストはまず低位ティアにヒットします。ヒットの場合、レスポンスが提供され、そこで終了します。ミスの場合、低位ティアは上位ティアに問い合わせます。そこでヒットした場合、レスポンスが返され、戻る途中で低位ティアにも保存されます。両方のティアがミスした場合にのみ、Workerが実際に実行されます。その実行からのレスポンスは両方のティアに保存されます。
[画像: BLOG-3262 image2]
これが重要な理由は、世界中の最初の要求が上位ティアを埋めるからです。その後、どのデータセンターからの後続のすべての要求も、Workerを実行せずに上位ティアから提供できます。たとえそのデータセンターの低位ティアがその要求を初めて見たことがなくてもです。キャッシュヒット率は、単一のフラットキャッシュレイヤーよりも劇的に高くなります。これは、Workerがオリジンである場合にまさに望むことです。
これは、ゾーン向けのTiered Cacheを今日動かしているのと同じトポロジーですが、設定は不要です。「Workerの階層型キャッシュをオンにする」ためのダイアログはありません。キャッシュが有効になっているすべてのWorkerは、無料で階層化を受け取ります。
WorkerがSmart Placementを使用している場合、キャッシュはそれとクリーンに構成されます。まずティアが参照され、両方がミスした場合にのみSmart Placementがオリジンに近い場所に実行をルーティングします。これらのレイヤーがどのように相互作用するかについては、さらに詳しく説明します。いくつかの粗いエッジについては、ドキュメントで平滑化する予定です。
ユーザーの近くとデータの近くでアプリを実行する
Webパフォーマンスには、誰も完全に解決していない繰り返し現れる緊張があります。コードはユーザーの近くで実行したい(ユーザーとサーバー間の往復はクリティカルパスにあるため)、そしてコードはデータの近くで実行したい(すべてのデータベースクエリも往復であるため)です。どちらかを選択すると、もう一方が遅くなります。
私たちは両方を追い求めて何年も費やしてきました。私たちのネットワークは、世界のインターネットユーザーの約95%に約50ms以内で到達できます。Smart PlacementとPlacement Hintsは、クラウドリージョンを考慮することなく、コードをデータに近づけることができます。しかし、これまで、この2つの部分は完全に構成されていませんでした。「ユーザーの近く」または「データの近く」のどちらかを選択でき、アプリの両方の部分が同時に正しい場所にあることを望む場合は、Cloudflareの専門家である必要がありました。私たちはもっとうまくやれると知っていました。
Workers Cacheは、ギャップを埋める部分です。キャッシュはWorker(ゾーンではない)に属し、サービスバインディングとWorker間のctx.exports呼び出しがキャッシュを通過するため、各Workerが実行されるべき場所で実行されるWorkerのチェーンとしてアプリを構築できます。キャッシュがそれらの間の継ぎ目となります。
アーキテクチャは次のようになります。
[画像: BLOG-3262 image8]
- Worker Aはユーザーの近くで実行されます。認証、レート制限、ルーティング、ヘッダー正規化、データに依存しないHTMLページの外側の「シェル」のレンダリングなど、すべてのリクエストの安価でレイテンシに敏感な部分を処理します。
- Worker Bは、Smart Placementまたは明示的なPlacement Hintのおかげで、データの近くで実行されます。サーバーレンダリングページ(データをフェッチする)、商品カタログの読み取り、検索結果の生成、APIの集約、コストのかかる変換など、重い作業を行います。
- Workers CacheはWorker Bの前に配置されます。Worker Aがサービスバインディング経由でWorker Bを呼び出すと、CloudflareはまずWorker Bのキャッシュを確認します。ヒットの場合、Worker Aはレスポンスを受け取り、Worker Bはまったく実行されません。データセンターホップ、データベースクエリ、レンダリング作業はありません。
キャッシュヒットパスは次のようになります:ユーザー → ユーザーの近くのWorker A → Worker Bのキャッシュヒット → レスポンス。データホップはミスの場合にのみ発生します。ホットページはユーザー前のコードの速度で実行され、コールドページは実行時にデータの近くで実行されるという利点があります。
これを得るために特別なアーキテクチャを設計する必要はありません。アプリを2つのWorkerとして書き、1つをサービスバインディングで他のものに向け、Worker Bのwrangler.jsoncファイルでキャッシュをオンにし、完了です。
[画像: BLOG-3262 image7]
デフォルトでマルチテナント、ctx.propsを使用
ユーザー固有のデータを返すWorker(たとえば、ログイン中のユーザーごとに異なるコンテンツを提供するAPI)をキャッシュしている場合、あるユーザーが別のユーザーのキャッシュされたレスポンスを決して見られないようにする方法が必要です。標準的な解決策は「認証されたリクエストはキャッシュしない」ことであり、Cloudflareの自動バイパスはAuthorizationヘッダーに対してまさにそれを実行します。しかし、「何もキャッシュしない」はパフォーマンス上の利点をすべて放棄します。
Workers Cacheは、呼び出し元のctx.propsをキャッシュキーの一部にすることでこれを解決します。あるWorkerがサービスバインディング経由で別のWorkerを呼び出し、ユーザーID、テナントID、またはその他の識別子を持つctx.propsを渡すと、異なるプロップを持つ呼び出し元は個別のキャッシュエントリを取得します。あるユーザーのレスポンスが別のユーザーのキャッシュに漏れることは決してありません。
import { WorkerEntrypoint } from "cloudflare:workers";
interface Props { userId: string; }
export default class Backend extends WorkerEntrypoint<Env, Props> {
async fetch(request: Request): Promise<Response> {
// ctx.props.userId はキャッシュキーの一部です。ユーザーAとユーザーBが
// 同じURLをリクエストすると、個別のキャッシュエントリが得られます。
const { userId } = this.ctx.props;
const data = await loadUserData(userId);
return new Response(JSON.stringify(data), {
headers: {
"Content-Type": "application/json",
"Cache-Control": "public, max-age=300",
},
});
}
}
典型的なパターンは、ゲートウェイWorkerでリクエストを認証し、Authorizationヘッダーを削除し、認証されたユーザーのIDをctx.propsに設定してから、キャッシュされたバックエンドWorkerを呼び出すことです。ゲートウェイはすべてリクエストで実行されます(認証する必要があるため)。しかし、コストのかかるバックエンドは、そのユーザーのキャッシュエントリがない場合にのみ実行されます。認証済みAPIは、「キャッシュ不能」から「ユーザーごとに安全にキャッシュ」に移行し、キャッシュキーが分離を行います。ドキュメントでは、Multi-tenant safety with ctx.propsとPer-user authenticated responsesの例でこれを詳細に説明しています。
他のCDNでは、正確さとヒット率のどちらかを選択する必要があります。各ユーザーのトークンでキャッシュをキー付けするか、すべてのリクエストをオリジンに送り返して認証するかです。Workers Cacheを使用すると、認証されたマルチテナントAPIの組み込みモデルとして、エッジでキャッシュされたAPIレスポンスを共有しながら、リクエストごとの認証境界を維持できます。これを提供している他のCDNは、私たちの知る限りありません。私たちはそれを誇りに思っています。
すべてのWorkerエントリポイント間のキャッシュ
Workers Cacheの最も大きなアンロックになると考えている部分であり、「Workerの前に機能するCDNキャッシュ」と考えている場合は最も見えにくい部分です。
Workers Cacheは、すべてのWorkerエントリポイントの前――デフォルトエクスポート、すべての名前付きWorkerEntrypoint、および同じWorker内のctx.exports経由の呼び出し――に配置されます。最後の句は、構築できるものを変えます。
あるエントリポイントがctx.exports経由で別のエントリポイントを呼び出すと、キャッシュはブラウザからのリクエストを評価するのと同じ方法でその呼び出しを評価します。ヒットはキャッシュされたレスポンスを返し、呼び出し先は実行されません。ミスは呼び出し先を実行し、そのレスポンスを独自のキャッシュキー(呼び出し先のエンティティポイント、パス、クエリ文字列、およびctx.propsでキー付け)の下に保存します。呼び出し元はすべてのリクエストで実行されますが、呼び出し先に渡すものはすべて個別にメモ化されます。
どのエントリポイントがキャッシュするかは、エントリポイントごとに決定します。Wrangler設定では、exportsマップを使用して、名前("default"はデフォルトエクスポート)で各エントリポイントのキャッシングをオンまたはオフにできます。エントリポイントをキャッシュにオプトインして生成されたレスポンスをキャッシュするか、オプトアウトしてすべてリクエストで実行し続けるかを選択します。ゲートウェイまたはルーターエントリポイント(認証、正規化、またはディスパッチを行うもの)はオプトアウトする必要があります。これにより、常に実行され、その出力がキャッシュから提供されることはありません。
これにより、構成可能なプリミティブが得られます。Workerを小さなエントリポイントのチェーン(認証、正規化、ルーティング、コストのかかる読み取り、データレイヤー)として作成し、Workers Cacheを好きな場所に配置できます。キャッシュされた各エントリポイントは、独自のキー、独自のTTL、およびパージ用の独自のタグ名前空間を持つメモ化の単位です。キャッシュについて構成したいこと(いつ実行するか、何をキーにするか、いつ無効にするか)は、通常のWorkerコードとして表現されます。どのエントリポイントを呼び出すか、どのリクエストを転送するか、どのctx.propsを渡すか、どのCache-Controlを設定するかです。
これを具体的にするために、3つのことを簡単に実行できない単一のWorkerを示します。すべてのリクエストを認証し、コストのかかるバックエンドをマルチテナントセーフなキャッシュキーでキャッシュし、データが変更されたときにそのキャッシュを無効にします。
キャッシュはエントリポイントごとに構成されます。ゲートウェイはすべてリクエストで実行する必要があります(認証のため、およびキャッシュされたゲートウェイレスポンスが認証チェックをスキップするため)。そのため、デフォルトエントリポイントのキャッシュを無効にし、内部エントリポイントのみで有効にします。
{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2026-05-01",
"cache": { "enabled": true },
"exports": {
// ゲートウェイはすべてリクエストで実行されます — キャッシュしないでください。
"default": { "type": "worker", "cache": { "enabled": false } },
// コストのかかる内部エントリポイントをキャッシュします。
"CachedBackend": { "type": "worker", "cache": { "enabled": true } }
}
}
import { WorkerEntrypoint } from "cloudflare:workers";
interface Env { API_TOKEN: string; }
interface Props { userId: string; }
// 内部エントリポイント:コストのかかる作業。Workers Cacheはこれの前に配置されます。
// ヒットの場合、このコードは実行されません。
export class CachedBackend extends WorkerEntrypoint<Env, Props> {
async fetch(request: Request): Promise<Response> {
// ctx.props.userId はキャッシュキーの一部なので、これは各ユーザーごとに
// 別々にキャッシュされます。
const { userId } = this.ctx.props;
const data = await loadExpensiveData(userId);
return new Response(JSON.stringify(data), {
headers: {
"Content-Type": "application/json",
"Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
"Cache-Tag": `user:${userId}`,
},
});
}
// 書き込み時にユーザーのキャッシュされたレスポンスを無効化します。
// purge() は呼び出したエントリポイントにスコープされるため、
// キャッシュされたレスポンスを所有するエントリポイントである CachedBackend 内で実行する必要があります。
async invalidate(userId: string): Promise<void> {
await this.ctx.cache.purge({ tags: [`user:${userId}`] });
}
}
// 外部エントリポイント:認証とルーティングのためにすべてリクエストで実行されます。
// Wrangler設定(上記)でキャッシュが無効になっているため、常に実行され、
// キャッシュヒットによって認証チェックがスキップされることはありません。
export default {
async fetch(request, env, ctx): Promise<Response> {
const userId = await authenticate(request, env);
if (!userId) return new Response("Unauthorized", { status: 401 });
// 書き込み時にこのユーザーのキャッシュを無効化します。これは、
// キャッシュされたレスポンスを所有するエントリポイントから行われます。
if (request.method === "POST") {
await handleWrite(request, userId);
await ctx.exports.CachedBackend.invalidate(userId);
return new Response("OK");
}
// 読み取りの場合:Authorizationヘッダーを削除します(そうしないとCloudflareの自動
// バイパスが発火し、何もキャッシュされません)。その後、認証された
// ユーザーのIDをctx.propsに渡して、キャッシュされたバックエンドにディスパッチします。
const forwarded = new Request(request);
forwarded.headers.delete("Authorization");
return ctx.exports.CachedBackend.fetch(forwarded, {
props: { userId },
});
},
} satisfies ExportedHandler<Env>;
すべては1つのWorkerです。1つのソースファイル。1つのデプロイ。しかし、2つの実行ステージがあります(ゲートウェイのキャッシュはオフ、バックエンドはオンに設定されており、1つの小さなexportsブロックで)。そして、それらの間にキャッシュが配置され、ユーザーごとにキー付けされ、書き込みパスによって無効化され、バックグラウンドリフレッシュ中に古いものを提供します。キャッシュステージは、後付けしたものではありません。プログラムのレイヤーであり、コードで記述されています。
これにより構成されるパターンは無限です。同じ形状が以下に適用されます。
- Durable Objectのキャッシュ。Durable Objectをエントリポイントでラップし、レスポンスに
Cache-Controlを設定すると、読み取りはヒット時にDurable Objectに触れなくなります。書き込みはDOに直接行われ、タグでキャッシュをパージします。DOはキャッシュが発生していることを認識しません。 Varyの前のAccept-Encodingの正規化。外部エントリポイントは、元のエンコーディングをrequest.cf.clientAcceptEncoding(Cloudflareの最前線がキャッシュ効率のために正規化します)から復元し、実際の値に依存するキャッシュエントリポイントに転送します。ヒット率は高く保たれ、クライアントは正しいエンコーディングを取得します。- キャッシュ前のトラッキングパラメータの削除。外部エントリポイントはURLを正規化します(または、キャッシュされた内部エントリポイントが正規化された形式のみを参照するように、
ctx.exports呼び出しでcf.cacheKeyを設定します)。これにより、?utm_source=anythingが単一のキャッシュエントリに折りたたまれます。
これらをスタックします。単一のWorkerは、認証とルーティングを行う外部エントリポイント、トラッキングパラメータを削除しエンコーディングヘッダーを復元する正規化エントリポイント、Durable Objectを前面に置くキャッシュエントリポイント、および認証されていない公開API用の別のキャッシュエントリポイントを持つことができます。それぞれが設定していないキャッシュステージによって接続されています。設定したのは、配置場所を決めただけです。ドキュメントのExamplesページでは、これらのいくつかをエンドツーエンドで説明しています。
私たちは、他のプラットフォームでこれができるとは知りません。CDNキャッシュはオリジンの前に配置されます。関数プラットフォームは関数を実行します。単一のデプロイ可能なユニット内に、アプリケーションの部分の間に配置され、各キャッシュステージがその両側のコードによって構成されるキャッシュを提供するプラットフォームは、私たちの知る限り他にありません。それがWorkers Cacheです。そして、プラットフォームがすでに提供している他のすべて(Smart Placement、Durable Objects、サービスバインディング、ctx.props、ctx.exports)と構成されるため、構築できるパターンは無限です。この投稿では、表面をかじったにすぎません。
フレームワークでのファーストクラスサポート
Astroで構築している場合、CloudflareアダプターはWorkers Cacheを自動的に設定します。設定にcacheCloudflareプロバイダーを追加するだけです。
// astro.config.mjs
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";
export default defineConfig({
adapter: cloudflare(),
output: "server",
experimental: {
cache: { provider: cacheCloudflare() },
routeRules: {
"/products/*": { maxAge: 300, swr: 3600, tags: ["products"] },
"/blog/*": { maxAge: 60, swr: 86400, tags: ["blog"] },
},
},
});
アダプターはキャッシュを有効にし、Astroが生成するレスポンスに正しいヘッダーを設定し、コンテンツが変更されたときにパージするためのcache.invalidate()ヘルパーを提供します。サーバーレンダリングをオプトインしたAstroページは、上記で説明した「一度レンダリング、キャッシュ、バックグラウンドでリフレッシュ」フローを自動的に取得します。ルートごとの設定や、学習する必要のあるフレームワーク固有のランタイムレイヤーは不要です。
私たちは他のフレームワークのメンテナーと協力して、同様の統合をリリースしています。Cloudflare用のフレームワークアダプターを構築する場合、Workers Cache APIはまさにあなたが望むものになります。ヘッダー駆動の設定、プログラムによるパージ、モデリングする必要のあるプラットフォーム固有の概念はありません。
Workerと同じダッシュボードでキャッシュを表示
キャッシュは、その動作を確認できなければ有用ではありません。Workers Observabilityダッシュボードは現在、呼び出しごとのキャッシュヒット情報を提供しています。
[画像: BLOG-3262 image6]
Workerごとに以下を確認できます。
- 時間経過に伴うキャッシュヒット率。キャッシュを有効にした後に上昇させたい数値。
- ヒット、ミス、更新、バイパスの内訳。ヒット率が低い場合、その理由をここで見つけます。
BYPASSレスポンスが多すぎる(クッキーが設定されているためか?)、MISSレスポンスが多すぎる(キャッシュキーが想定以上に分割されているためか?)、UPDATINGレスポンスが多すぎる(max-ageがトラフィック間隔より短いか?)
これらすべてがWorkerの他のオブザーバビリティ(ログ、例外、CPU時間、リクエスト数)と同じダッシュボード上にあるため、何が起こっているかを理解するためにゾーンとWorkerの間でコンテキストスイッチする必要はありません。
請求
キャッシュヒットはWorkerを実行しないため、CPU時間の請求もありません。それらは、他のすべての呼び出しと同様に、標準のWorkersリクエストレートとしてリクエストとしてカウントされます。キャッシュミスとバイパスは通常通り請求されます。リクエスト + CPU時間、キャッシュなしの場合とまったく同じです。
| 結果 | リクエスト課金 | CPU時間課金 |
|---|---|---|
| キャッシュヒット(Workerは実行されない) | 標準レート | 請求なし |
| キャッシュミス(Workerは実行される) | 標準レート | 請求あり |
| キャッシュバイパス(Workerは実行される) | 標準レート | 請求あり |
| 静的アセットリクエスト | 標準レート | 請求なし |
| Worker間呼び出し | 標準レート | Workerが実行された場合は請求あり |
個別のWorkers Cache SKUやGBあたりのキャッシュストレージ料金はありません。階層型キャッシュ、パージ、stale-while-revalidate、および上記のアナリティクスはすべて含まれています。リクエストがWorkerを実行するはずだったのにWorkers Cacheが代わりにヒットとして提供した場合、標準リクエストレートは請求されますが、そのリクエストのCPU時間は請求されません。このため、そのキャッシュヒットはWorkerで同じレスポンスをレンダリングするよりもコストがかかりません。
注意すべき点:キャッシュが有効になっている場合、通常無料のリクエスト(静的アセットリクエストとサービスバインディングまたはctx.exportsを介したWorker間呼び出し)は、それぞれがWorkerの前にキャッシュをチェックするため、標準リクエストレートで請求されます。
次は何ですか
次にやりたいと考えていること:
- Smart Placementとのよりスマートな共同配置。現在、Cloudflareは上位ティアキャッシュとSmart Placementターゲットを個別に選択します。完全なミスの場合、リクエストはCloudflareの場所間を2回移動する可能性があります。上位ティアをチェックするために1回、そしてデータに近い場所でWorkerを実行するために再度移動します。これらの選択を調整して、ミスが一度だけ長距離移動するように取り組んでいます。
- より大きなレスポンスサイズ制限。ローンチ時、すべてのレスポンスは、アカウントに関係なく、Freeプランのキャッシュ可能サイズ制限(512 MB)に従います。これは一時的なものです。ロールアウトステップが完了すると、標準のプランごとのキャッシュ制限が適用されます。
- より多くのフレームワーク統合。AstroにはWorkers Cacheとの組み込み統合があります。他のフレームワーク(TanStack StartやVinext経由のNext.jsを含む)のメンテナーと協力して同様の統合を追加しています。
- キャッシュされたレスポンスを古いとマークするAPI。
ctx.cache.purge()は一致するレスポンスをキャッシュから削除します。一致するレスポンスを期限切れとして扱うctx.cache.invalidate()APIを検討しています。これにより、次のリクエストは古いレスポンスを高速に取得し、Workerがバックグラウンドでキャッシュをリフレッシュできます。
試してみてください
Workers Cacheは、すべてのプランのすべてのWorkerで今日から利用可能です。
開始するには、wrangler.jsoncに"cache": { "enabled": true }を追加し、再デプロイして、Cache-Controlヘッダーの設定を開始してください。Workers Cacheドキュメントでは、クイックスタート、キャッシュキー、パージ、構成パターンと例、およびデバッグを含む、機能の全表面を説明しています。
Workerはキャッシュの前に実行されていました。今ではその後ろでも実行できます。必要な側を使用してください。または、サービスバインディングを使用すれば、両方を同時に使用できます。
皆さんが構築するものを見るのが待ちきれません。