共享字典

共享字典（RFC 9842 ↗）允许源站基于访问者浏览器已缓存的同一资源（或另一资源）的副本压缩响应。线上只传输两个资源之间的差异。

这对部署之间增量变更的版本化资产最有效，例如 JavaScript 打包文件、CSS 文件和框架分块。部署后，回访用户可收到相对于已有版本的小增量，而无需重新下载整个文件。

Cloudflare 以 **passthrough（透传）**模式支持共享字典：由你的源站管理字典并生成差分压缩响应。Cloudflare 转发字典相关标头以及 dcb/dcz 内容编码，不做修改或重新压缩，并对缓存进行变体区分，使每个差分压缩变体分别存储。

关于 Cloudflare 支持的其他压缩算法的背景信息，请参阅 内容压缩。

共享字典在以下条件全部满足时生效：

• 访问者的浏览器支持 压缩字典传输 ↗。目前为 Chrome 130 或更高版本、Edge 130 或更高版本，或其他同版本的 Chromium 浏览器。
• 浏览器请求在 Accept-Encoding 中包含 dcb 或 dcz，并带有 Available-Dictionary 标头。
• 你的源站返回差分压缩响应，且 Content-Encoding: dcb 或 dcz，以及包含 Accept-Encoding, Available-Dictionary 的 Vary 标头。
• 字典、差分响应和请求均通过同一源站的 HTTPS 提供。根据 RFC 9842，第 8 节 ↗，压缩字典传输仅支持 HTTPS。

该协议使用两个新的请求/响应标头和两种新的内容编码：

版本化资产的首次响应包含 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=:）。冒号是语法的一部分。

启用共享字典分两部分完成：

1. 在 Cloudflare 中为你的 zone 打开透传。这会告知 Cloudflare 正确转发字典标头并对缓存条目做变体区分。
2. 更新源站服务器，将资产标记为字典，并返回基于它们的差分压缩响应。

创建字典以及相对字典压缩新响应的工作在源站完成，而不是在 Cloudflare 上。

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"
	}'

对于每个要用作字典的版本化资产，在首次响应中包含 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，不支持正则表达式，且必须解析到与字典相同的源站。

当请求带有 Available-Dictionary 标头时，按 SHA-256 哈希查找字典。若你持有该字典，则相对其压缩响应并返回：

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

RFC 9842，第 6.2 节 ↗ 要求 Vary: Accept-Encoding, Available-Dictionary 响应标头，以免浏览器缓存提供错误的变体。在透传开启时，Cloudflare 的缓存也会按这些标头做变体区分。

当浏览器未通告 Available-Dictionary、哈希与你持有的字典不匹配，或浏览器未通告 dcb/dcz 时，使用常规的 Brotli、Zstandard 或 Gzip 压缩返回响应。

Cloudflare 不规定具体的源站实现。常见起点包括：

• 反向代理。 配置 NGINX、Caddy 或类似代理以附加 Use-As-Dictionary 标头，并通过 sidecar 进程生成差分响应。
• 应用服务器原生支持。 扩展现有压缩中间件以读取 Available-Dictionary 并输出 dcb 或 dcz。

要确认请求正在使用共享字典，请对资产请求两次。第二次请求会通告你在首次响应中收到的字典。

# 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

第二次响应应包含 Content-Encoding: dcz（或 dcb）、Vary: Accept-Encoding, Available-Dictionary，以及明显小于非差分响应的 Content-Length。

你也可以使用 canicompress.com ↗ 确认浏览器是否支持共享字典，并检查可用的差分压缩响应。

• 需要源站侧工作。 在透传模式下，Cloudflare 不会生成字典或计算差分。若源站不产生 dcb/dcz 响应，则不会有压缩收益。
• 修改正文的功能不兼容。 会改写响应正文的 Cloudflare 功能不适用于差分压缩响应。请在字典压缩路径上关闭这些功能，或在源站响应上设置 cache-control: no-transform。详情请参阅 内容压缩。
• 浏览器支持不完整。 未请求 dcb 或 dcz 的浏览器访问者仍会按你现有的 Compression Rules 和 默认压缩行为 接收 Brotli、Zstandard 或 Gzip。
• 仅限同源。 根据 RFC 9842，第 9.3.1 节 ↗，字典限定在响应源站范围内。不支持跨源使用字典。