Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

共有辞書

最終更新 Markdown で表示Agent セットアップ

共有辞書（RFC 9842 ↗）を使うと、オリジンは訪問者のブラウザーがすでにキャッシュしている、同じ（または別の）リソースを基準にレスポンスを圧縮できます。回線上を流れるのは、2 つのリソースの差分だけです。

デプロイごとに少しずつ変わるバージョン付きアセット（JavaScript バンドル、CSS ファイル、フレームワークのチャンクなど）で特に効果があります。デプロイ後、再訪者はファイル全体を再ダウンロードせず、手元にあるバージョンに対する小さな差分として新しいアセットを受け取れます。

Cloudflare は共有辞書を passthrough モードでサポートします。辞書の管理と差分圧縮レスポンスの生成はオリジン側で行います。Cloudflare は辞書ヘッダーと dcb / dcz のコンテンツエンコーディングを変更も再圧縮もせず転送し、キャッシュを Vary して、差分圧縮された各バリアントを個別に保存します。

Cloudflare が対応するほかの圧縮アルゴリズムの背景は、コンテンツ圧縮 を参照してください。

利用可否

Free Pro Business Enterprise
利用可否 はい（ベータ） はい（ベータ） はい（ベータ） はい（ベータ）

要件

共有辞書は、次の条件をすべて満たすときに動作します。

  • 訪問者のブラウザーが compression dictionary transport ↗ に対応していること。現時点では Chrome 130 以降、Edge 130 以降、または同じバージョンの Chromium 系ブラウザーです。
  • ブラウザーのリクエストに、Accept-Encoding 内の dcb または dcz と、Available-Dictionary ヘッダーが含まれること。
  • オリジンが Content-Encoding: dcb または dcz の差分圧縮レスポンスを返し、Vary ヘッダーに Accept-Encoding, Available-Dictionary が含まれること。
  • 辞書、差分レスポンス、リクエストが、同じオリジンから HTTPS で配信されること。RFC 9842, Section 8 ↗ のとおり、圧縮辞書転送は HTTPS 専用です。

共有辞書の仕組み

このプロトコルは、新しいリクエスト / レスポンスヘッダーを 2 つと、新しいコンテンツエンコーディングを 2 つ使います。

ヘッダー 方向 用途
Use-As-Dictionary オリジン → ブラウザー 指定した match 値に一致する今後のリクエストで、辞書として使えるレスポンスであることを示します。
Available-Dictionary ブラウザー → オリジン リクエスト URL 向けにブラウザーがすでに持っている辞書の SHA-256 ハッシュを通知します。
Content-Encoding: dcb または dcz オリジン → ブラウザー 通知された辞書を基準に差分圧縮します。Brotli（dcb）または Zstandard（dcz）を使います。

バージョン付きアセットの最初のレスポンスには Use-As-Dictionary が含まれ、ブラウザーはそのレスポンスを保存します。パターンに一致するアセットへの以降のリクエストでは、ブラウザーは Available-Dictionary: :<sha256>: を送り、Accept-Encoding に dcb, dcz を追加します。オリジンは新しいアセットを辞書を基準に圧縮し、Content-Encoding: dcb または dcz で返します。ブラウザーは保存済みのコピーを使って、完全なレスポンスを再構築します。

Use-As-Dictionary の match 値は WHATWG URL Pattern ↗ であり、正規表現ではありません。マッチパターンはパーセントエンコードされた URL パスに対して動作し、辞書と同じオリジンにスコープされます。

Available-Dictionary の値は Structured Field ↗ のバイト列です。base64 エンコードした SHA-256 ハッシュをコロンで囲みます（例: :pZGm1Av0IEBKARczz7exkNYsZb8LzaMrV7J32a2fFG4=:）。コロンは構文の一部です。

共有辞書を有効にする

共有辞書の有効化は 2 つの作業です。

  1. Cloudflare でゾーンの passthrough をオンにします。辞書ヘッダーの転送と、キャッシュエントリの正しい Vary を Cloudflare に指示します。
  2. オリジンサーバーを更新し、アセットを辞書としてマークし、それを基準にした差分圧縮レスポンスを返すようにします。

辞書の作成と、新しいレスポンスを辞書で圧縮する処理は、Cloudflare ではなくオリジン側で行います。

1. Cloudflare で passthrough を有効にする

ダッシュボードで共有辞書を有効にするには、次の手順を行います。

  1. Cloudflare ダッシュボードで Speed の Settings ページを開きます。

    Settings を開く ↗

  2. Content Optimization を開きます。

  3. Shared Dictionaries を On にします。

次の PATCH リクエストで共有辞書を有効にします。

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/settings/shared_dictionary_mode" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"value": "passthrough"
	}'

共有辞書をオフにするには、value を "disabled" に設定します。

この設定で使える値は次のとおりです。

値 動作
passthrough Cloudflare は共有辞書のリクエスト / レスポンスヘッダーを転送し、オリジンからの dcb / dcz レスポンスを受け付け、キャッシュエントリを Vary します。
disabled Cloudflare は共有辞書ヘッダーを取り除き、dcb / dcz バリアントはキャッシュしません。

cloudflare_zone_settings_override リソースで共有辞書を設定できます。詳細は Terraform のドキュメント ↗ を参照してください。

2. オリジンでアセットを辞書としてマークする

辞書として使う各バージョン付きアセットについて、最初のレスポンスに Use-As-Dictionary ヘッダーを付けます。

Use-As-Dictionary: match="/static/app-*.js", type="raw"
Cache-Control: public, max-age=31536000, immutable
Content-Encoding: br

match 値は、今後どのリクエスト URL でこの辞書を通知するかをブラウザーに伝えます。WHATWG URL Pattern であり、正規表現は使えません。辞書と同じオリジンに解決される必要があります。

3. 通知された辞書を基準に新しいバージョンを圧縮する

Available-Dictionary ヘッダー付きのリクエストが届いたら、SHA-256 ハッシュで辞書を探します。見つかった場合は、それを基準にレスポンスを圧縮して返します。

Content-Encoding: dcz
Vary: Accept-Encoding, Available-Dictionary
Cache-Control: public, max-age=31536000, immutable

RFC 9842, Section 6.2 ↗ は、ブラウザーキャッシュが誤ったバリアントを返さないよう、Vary: Accept-Encoding, Available-Dictionary レスポンスヘッダーを必須にしています。passthrough がオンのとき、Cloudflare のキャッシュもこれらのヘッダーで Vary します。

4. 辞書がないときのフォールバック

ブラウザーが Available-Dictionary を通知しない場合、ハッシュが手元の辞書と一致しない場合、またはブラウザーが dcb / dcz を通知しない場合は、通常の Brotli、Zstandard、または Gzip 圧縮でレスポンスを返します。

実装の選択肢

Cloudflare は特定のオリジン実装を指定しません。よくある出発点は次のとおりです。

  • リバースプロキシ。 NGINX、Caddy、または同様のプロキシで Use-As-Dictionary ヘッダーを付与し、サイドカープロセスで差分レスポンスを生成します。
  • アプリケーションサーバーのネイティブ対応。 既存の圧縮ミドルウェアを拡張し、Available-Dictionary を読んで dcb または dcz を出力します。

共有辞書をテストする

リクエストが共有辞書を使っていることを確認するには、同じアセットを 2 回リクエストします。2 回目のリクエストでは、1 回目のレスポンスで受け取った辞書を通知します。

# Prime the dictionary.
curl -sI -H "Accept-Encoding: br, gzip, zstd, dcb, dcz" \
  https://example.com/static/app.v1.js

# Request the next version, advertising the dictionary you just received.
# Replace <hash> with the base64-encoded SHA-256 of the first response.
# The surrounding colons are part of the Structured Field syntax
# and are required by RFC 9842, Section 2.2.
curl -sI -H "Accept-Encoding: br, gzip, zstd, dcb, dcz" \
  -H "Available-Dictionary: :<hash>:" \
  https://example.com/static/app.v2.js

2 回目のレスポンスには Content-Encoding: dcz（または dcb）、Vary: Accept-Encoding, Available-Dictionary が含まれ、Content-Length は差分でないレスポンスより大幅に小さくなります。

canicompress.com ↗ でも、ブラウザーが共有辞書に対応していることと、実際の差分圧縮レスポンスを確認できます。

制限事項

  • オリジン側の作業が必要です。 passthrough モードでは、Cloudflare は辞書を生成せず、差分も計算しません。オリジンが dcb / dcz レスポンスを返さないと、圧縮による節約は起きません。
  • 本文を書き換える機能とは併用できません。 レスポンス本文を書き換える Cloudflare の機能は、差分圧縮レスポンスでは動きません。辞書圧縮するパスではこれらの機能をオフにするか、オリジンレスポンスに cache-control: no-transform を設定してください。詳細は コンテンツ圧縮 を参照してください。
  • ブラウザー対応は部分的です。 dcb または dcz を要求しないブラウザーの訪問者は、既存の Compression Rules と デフォルトの圧縮動作 に従い、Brotli、Zstandard、または Gzip を受け取ります。
  • 同一オリジンのみです。 RFC 9842, Section 9.3.1 ↗ のとおり、辞書はレスポンスのオリジンにスコープされます。クロスオリジンでの辞書利用はサポートしていません。

役に立ちましたか？