企业官网建设流程全解析

Cloudflare Workers 兼容性标志cache_no_cache_enabled全解析：在fetch()中启用标准cache: no-cache

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs

cache_no_cache_enabled是 Cloudflare Workers 在 2025-08-07 随兼容性日期默认启用的一组兼容性标志，它让开发者可以在 Worker 发起的子请求中，通过fetch()与Request初始化参数指定标准 HTTP 语义的cache: "no-cache"，从而强制 Cloudflare 缓存与源站重新验证。本文以仓库中的 cache-no-cache.md 为骨架，结合 fetch() API 文档 与兼容性标志的配置文档，完整讲解该标志的前置条件、开启后的请求行为、缓存重验证流程、代码示例，以及如何通过 Wrangler、Dashboard 与 API 开关它。读完你将能正确地在 Worker 中强制按需重验证源站资源，并理解它与cache: "no-store"的区别。

标志总览：front matter 中的关键元数据

该文档的 front matter 定义了标志的完整元信息，是理解其生命周期与开关方式的起点：

从仓库的 compatibility-flags.ts 可以看到，所有兼容性标志的 schema 统一包含name、enable_date、enable_flag、disable_flag、sort_date以及可选的experimental字段。而 compatibility-flags.json.ts 则把src/content/compatibility-flags/目录下全部标志聚合为一个 JSON 端点（省略sort_date，并将正文作为description输出），这意味着本文档的内容同样会被程序化消费，例如供 Dashboard 或自动化工具展示。

关键事实：由于enable_date与sort_date均为2025-08-07，对于compatibility_date设定在2025-08-07或之后的 Worker，该行为默认开启，无需任何配置；旧 Worker 则需要显式加入cache_no_cache_enabled。

未启用时的行为：TypeError保护

文档明确说明了未开启时的兜底逻辑：

当未启用cache_no_cache_enabled，或设置了cache_option_disabled时，Workers 运行时会抛出TypeError，错误信息为Unsupported cache mode: no-cache。

这包含两种触发条件：

1. 未启用cache_no_cache_enabled：例如 Worker 的compatibility_date早于2025-08-07，且没有显式加入该标志；
2. 设置了cache_option_disabled：这是cache_option_enabled（cache: "no-store"支持）的禁用标志。由于cache: "no-cache"与cache: "no-store"同属fetch()的cache选项体系，当no-store支持被整体关闭时，no-cache也会一并失效并抛出TypeError。

同时，仓库中的 fetch() API 文档 对这一约束给出了更完整的表述：cache选项的合法取值只有undefined | 'no-store' | 'no-cache'三种；指定任何其他值（如浏览器端的default、reload、force-cache等）都会抛出TypeError，错误信息为Unsupported cache mode: <attempted-cache-mode>。

启用后的效果：重新验证而非绕过缓存

文档将no-cache的行为归纳为两点：

• 所有请求都会附带Pragma: no-cache与Cache-Control: no-cache两个请求头，向源站明示"请返回可用的缓存校验信息"；
• 对非 Cloudflare 托管的源站发起的子请求，会强制 Cloudflare 的缓存与源站重新验证（revalidate）。

这与no-store有本质区别：no-store（由cache_option_enabled标志支持，参见 cache-no-store.md）同样会给请求加上Pragma: no-cache与Cache-Control: no-cache，但对非 Cloudflare 托管源站的行为是完全绕过 Cloudflare 缓存；而no-cache则保留缓存命中可能性，只是强制在响应前向源站确认缓存是否仍然有效。

需要特别注意的是：该行为作用于Worker 内部发起的子请求（subrequest），而不是直接控制客户端到 Worker 的请求缓存策略。

缓存重验证的完整流程

文档给出了启用后请求经过 Cloudflare 缓存时的三步决策过程：

1. 先在 Cloudflare 缓存中查找匹配项；
2. 命中时：无论该缓存条目是新鲜的（fresh）还是已过期的（stale），都会向源站发送一个条件请求（conditional request）。若源站确认资源未变化，则直接返回缓存版本；若资源已变化，则从源站下载最新内容、更新缓存并返回该新内容；
3. 未命中时：Worker 向源站发起标准请求，并将响应写入缓存后返回。

这个"命中即条件请求、无视新鲜度"的设计，正是Cache-Control: no-cache的 HTTP 标准语义——允许使用缓存，但每次使用前都必须经过源站验证，从而在"尽可能少回源"与"保证内容最新"之间取得平衡。对于命中且资源未变化的场景，源站只需返回 304 之类的验证响应，流量成本远低于完整下载。

代码示例：两种指定方式

文档提供了两种等价的写法，均可直接复制使用。

方式一：在fetch()的 options 中指定

const response = await fetch("https://example.com", { cache: "no-cache" });

方式二：构造Request对象后传入fetch()

const request = new Request("https://example.com", { cache: "no-cache" }); const response = await fetch(request);

两种方式的语义完全一致：cache属性既可以作为RequestInit的选项直接传入fetch()，也可以在构造Request时固化到请求对象上。后者适合需要先构建、校验或复用同一个请求对象再发起的场景。

如何开启或关闭该标志

根据 compatibility-flags.mdx 的说明，兼容性标志有三条配置通道：

1. 通过 Wrangler 配置文件

在wrangler.jsonc（或wrangler.toml）中设置compatibility_date与compatibility_flags：

{ // 将兼容性日期固定在 2025-08-07 之前，以便按需逐项开启新行为 "compatibility_date": "2025-08-06", // 显式启用 no-cache 支持 "compatibility_flags": ["cache_no_cache_enabled"] }

若你的compatibility_date已晚于2025-08-07（默认已开启）但出于兼容性考虑想关闭该行为，则应加入cache_no_cache_disabled：

{ "compatibility_date": "2025-08-07", "compatibility_flags": ["cache_no_cache_disabled"] }

2. 通过 Cloudflare Dashboard

在 Cloudflare Dashboard 中进入 Worker 的 Settings → Compatibility flags（兼容性标志）面板，添加或移除对应标志即可。

3. 通过 Cloudflare API

调用 Workers Script API 更新 Worker，或在创建新版本（Workers Versions API）时，在请求体的metadata字段中携带compatibility_flags数组。这与该仓库 compatibility-flags.json.ts 输出的 JSON 结构保持一致。

相关标志对照与选型建议

为了不混淆，下表将cache选项体系中的两个标志并列对照：

两者的共同点是都会在请求上附加Pragma: no-cache与Cache-Control: no-cache头，且都只支持这两个取值（fetch() API 文档）。选型建议：

• 需要每次都拿到源站最新内容、但允许 304 复用缓存时，用no-cache；
• 需要完全跳过缓存读取（例如包含敏感数据、要求不可缓存的请求）时，用no-store；
• 如果代码中出现了这两个取值以外的cache值，运行时会抛出Unsupported cache mode的TypeError，请确保只使用no-store与no-cache。

与 Cache API 的边界

cache: "no-cache"作用于fetch()发起的子请求，属于通过标准 HTTP 头驱动 Cloudflare 缓存决策的路径。仓库中另有面向 Cache API 的兼容性标志cache_api_request_cf_overrides_cache_rules（见 cache-api-request-cf-overrides-cache-rules.md），它处理的是请求cf对象中的缓存设置对缓存规则的覆盖问题，仅适用于用户自有或灰云（grey-clouded）站点，两者分工不同：前者是标准 HTTP 语义的请求选项，后者是 Cache API 的配置覆盖。

小结

cache_no_cache_enabled将标准 HTTP 的no-cache语义完整地带入了 Workers 运行时：开启后，Worker 内的子请求可以用fetch(url, { cache: "no-cache" })或new Request(url, { cache: "no-cache" })驱动 Cloudflare 缓存与源站做条件重验证，在命中未变更资源时以极小回源成本返回最新内容。该标志自2025-08-07起默认启用，可通过cache_no_cache_disabled显式关闭；其完整行为、支持取值与配置方式均可在本文引用的 cache-no-cache.md、fetch() API 文档 与 兼容性标志总览 中进一步查阅。

【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs