Cloudflare Workersrequest_signal_passthrough兼容性标志让入站请求的 AbortSignal 自动传导至子请求【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本文深入讲解 Cloudflare Workers 中的request_signal_passthrough兼容性标志Compatibility Flag当启用该标志后入站请求incoming request的AbortSignal会在使用fetch()API 转发子请求subrequest时自动透传使子请求的取消行为与入站请求保持一致同时提供配套的no_request_signal_passthrough标志用于关闭该行为。文章将结合本仓库中的官方文档、Compatibility Flags 数据模型与 Wrangler 配置说明帮助你理解该标志的语义、如何在wrangler.jsonc中配置、它与enable_request_signal标志的关系以及在实际的代理/网关类 Worker 中如何利用请求取消传播机制构建更健壮的代码。标志概述与来源该标志的官方定义位于仓库的 request-signal-passthrough.md其 frontmatter 声明了关键元数据名称Passthrough AbortSignal of incoming request to subrequests启用标志request_signal_passthrough禁用标志no_request_signal_passthrough排序日期2025-05-05该标志的核心语义非常明确当request_signal_passthrough被设置时入站请求的AbortSignal会在请求被通过fetch()API 转发到子请求时透传给子请求。反过来当设置no_request_signal_passthrough时入站请求的AbortSignal将不会被透传。这种「启用 / 禁用」成对出现的标志设计是 Cloudflare Workers Compatibility Flags 体系的通用模式——它允许开发者既可以选择提前开启尚未默认生效的行为也可以在某个行为成为默认值之后显式地将其关闭以保持既有代码的兼容性。为什么需要透传 AbortSignal请求取消的级联要理解这个标志的价值需要先了解 Workers 中的请求取消机制。在 Workers 运行时中AbortController和AbortSignal提供了标准的异步操作取消模型。通过 Request.signal 这一只读属性你可以获得与入站请求对应的AbortSignal在启用了enable_request_signal兼容性标志后你还可以通过request.signal.addEventListener(abort, ...)监听客户端断开连接的事件执行日志记录或资源清理等收尾工作。一个典型的代理型 Worker 通常这样工作export default { async fetch(request, env, ctx) { // 将入站请求转发到源站或其他服务 const upstream await fetch(https://origin.example.com, request); return upstream; }, } satisfies ExportedHandlerEnv;在这个场景中如果客户端在上游响应返回之前中断了连接例如用户关闭了浏览器标签页、网络抖动入站请求会被取消。在未启用request_signal_passthrough的情况下通过fetch()发起的子请求不会继承入站请求的AbortSignal因此子请求仍然会继续向源站发送、完成并占用上游资源直到它自然结束。启用request_signal_passthrough之后情况发生变化子请求会继承入站请求的AbortSignal一旦客户端取消入站请求正在进行中的子请求也会被同步取消从而及时释放 Worker 与上游源站之间的连接资源避免为注定无人接收的响应继续消耗 I/O 与 CPU在网关、代理、聚合类 Worker 中形成「客户端断开 → 全链路取消」的级联取消cancellation propagation效果。这正是文档中「AbortSignal of an incoming request will be passed through to subrequests」所要表达的完整含义取消信号不再局限于当前 Worker 的入口而是沿着fetch()调用链向下传播。在 Wrangler 配置中启用标志Compatibility flags 通过 Worker 的 Wrangler 配置文件中的compatibility_flags字段进行设置该字段在 wrangler 配置文档 中被定义为string[]类型的可选数组通常与compatibility_date配合使用。例如在wrangler.jsonc中启用request_signal_passthrough{ name: my-proxy-worker, main: ./src/index.ts, compatibility_date: 2025-06-01, compatibility_flags: [request_signal_passthrough] }compatibility_date格式为yyyy-mm-dd的日期字符串用于确定 Workers 运行时采用哪个版本的行为。compatibility_flags启用或关闭特定功能的字符串数组适用于「提前开启未默认生效的新行为」或「关闭已经成为默认值、但你的代码仍依赖旧行为」的情况。参考 Compatibility flags 概览。如果希望显式关闭透传行为例如新代码依赖子请求不继承取消信号的旧语义则使用no_request_signal_passthrough{ compatibility_date: 2025-06-01, compatibility_flags: [no_request_signal_passthrough] }其他配置途径除了 Wrangler 配置文件兼容性标志还可以在以下位置设置参见 Compatibility flags 文档Cloudflare Dashboard在 Worker 的 Settings 中更新Cloudflare API在使用 Workers Script API 或 Workers Versions API 上传 Worker 时在请求体的metadata字段中设置。CLI 场景下wrangler deploy/wrangler dev命令 也支持通过--compatibility-date等参数覆盖配置方便本地调试时快速验证标志行为。与enable_request_signal的关系与区分在仓库中还存在一个语义相近但职责不同的标志request-signal.md 定义了enable_request_signal禁用标志为disable_request_signal其作用是让入站请求的Request.signal可用——允许你为入站请求的AbortSignal挂载事件监听器从而在客户端取消请求时执行日志记录、清理任务等操作。两个标志的分工可以这样理解标志作用对象核心能力enable_request_signal入站请求本身允许监听request.signal上的abort事件request_signal_passthrough由fetch()发起的子请求将入站请求的AbortSignal透传给子请求enable_request_signal解决的是「感知」取消——让你有机会在请求被取消时运行自己的收尾代码request_signal_passthrough解决的是「传播」取消——让子请求与入站请求同生共死。两者可以独立启用也可以组合使用。组合场景下的完整形态是既能在入口监听abort事件做清理与日志又能让转发给上游的子请求自动随客户端断开而取消。实战示例结合监听与透传构建可感知取消的代理以下示例综合运用两个标志演示一个既能感知取消、又能让取消自动向下传播的代理 Worker。对应的request.signal.addEventListener(abort, ...)监听模式参考仓库中的官方示例 request-signal-example.mdx。export default { async fetch(request, env, ctx) { // 感知阶段客户端断开时记录日志并触发清理 request.signal.addEventListener( abort, () { console.log(Client disconnected, propagating cancellation downstream.); // 此处可放置清理逻辑例如释放缓存、上报指标等 }, { once: true } ); // 传播阶段启用 request_signal_passthrough 后 // 此子请求会自动继承 request.signal // 客户端断开时上游 fetch 也会被同步取消。 const upstream await fetch(https://origin.example.com, { method: request.method, headers: request.headers, body: [GET, HEAD].includes(request.method) ? undefined : request.body, }); return upstream; }, } satisfies ExportedHandlerEnv;对应的 Wrangler 配置{ name: cancel-aware-proxy, main: ./src/index.ts, compatibility_date: 2025-06-01, compatibility_flags: [enable_request_signal, request_signal_passthrough] }需要注意的运行时约束fetch()属于异步任务必须在 handler 内调用不能在全局作用域执行。这与透传行为本身无关但它是任何代理型 Worker 落地前都必须满足的前提条件。底层机制与设计要点从运行时的角度透传的核心机制可以概括为Workers 运行时为每个入站请求维护一个AbortSignal当启用request_signal_passthrough后运行时在初始化由fetch()发起的子请求时会将该AbortSignal关联到子请求上客户端断开、入站请求触发 abort 时关联的子请求随即被取消运行时可以立即终止对应的上游连接与资源分配当设置no_request_signal_passthrough时第 2 步的关联被跳过子请求独立于入站请求的生命周期。在设计上该标志以sort_date: 2025-05-05进入 Compatibility Flags 体系见 request-signal-passthrough.md 的 frontmatter与enable_request_signalsort_date: 2025-05-22同属 2025 年上半年引入的请求取消能力家族。这些标志共同构成了 Workers 平台围绕「请求取消」的完整能力拼图先让取消事件可被感知再让取消信号沿调用链传播。开发者应当注意该行为在未来的兼容性演进Compatibility Flags 往往会在某个兼容性日期compatibility date之后成为默认行为。届时如果你的代码依赖「子请求不继承取消信号」的旧语义就需要显式声明no_request_signal_passthrough来保持行为不变反之如果在默认开启之前就想利用透传能力则提前声明request_signal_passthrough即可无需等待默认日期。总结request_signal_passthrough是 Cloudflare Workers 中围绕请求取消传播的一枚小而关键的兼容性标志启用request_signal_passthroughfetch()子请求自动继承入站请求的AbortSignal客户端断开时子请求同步取消适合代理、网关、BFF 等转发型 Worker显式关闭no_request_signal_passthrough子请求独立于入站请求的生命周期用于保持依赖旧语义的代码行为不变与enable_request_signal配合可同时实现「监听取消事件做清理」与「把取消信号传播给下游」的完整取消处理链路。配置时只需要在wrangler.jsonc的compatibility_flags数组中按需加入对应标志并结合compatibility_date管理运行时版本行为即可。理解并善用这一标志能帮助你在高并发的代理类场景下显著减少无效的上游请求提升整体资源利用效率。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考