gateway-workers

Gateway Workers 是一个面向 Cloudflare Workers 开发与审查的技能，针对由 Gateway HTTP 策略中 Forward 动作调用的 Workers。其使用前提是阅读当前 Forward 指南，按需获取相关页面，避免凭记忆复制配置、API 载荷或限制。

用途

用于构建、调试或审查 Gateway 在允许的 HTTP 流量上调用的 Worker，覆盖请求变换、合成响应与后台任务等场景。

主要能力与实现要求

检查现有 Worker，并按所需变换选择对应 Worker 模板。
从 cloudflare:workers 导出名为 GatewayMiddleware 的类，继承 WorkerEntrypoint，实现 handle(request, context, next) 并返回 Response；Gateway 通过 RPC 调用该方法，仅有默认 fetch() 处理器不满足 Forward 契约。
TypeScript 项目遵循所选模板当前的包安装与类型导入说明。
第二个参数用于获取 Gateway 上下文，描述原始请求，即使 Worker 修改请求也保持不变；需与 this.ctx（Workers 执行上下文）和 this.env（绑定）区分。
通过 next(request) 继续用户请求，最多一次；也可不调用而直接返回合成响应。next() 始终指向原始目标，对目标 URL 或主机的修改会被忽略，不能用于重定向、重试或扇出；访问其他目标需用 fetch()，它创建独立子请求，不继承用户的 Gateway 策略或出口配置。

上下文使用

按官方发布的类型与上下文参考确定字段名与可用性。将假值身份（!identity）视为匿名，并防护可选态势值；仅在需要时调用 await context.identity() 或 await context.devicePosture()，两者均可能拒绝，需将查询失败与值缺失分开捕获并决定处理方式。应使用 Gateway 提供的身份，而非客户端提供的身份头。

Gateway 行为与限制

仅首个匹配的 Forward 策略会调用 Worker；Worker 被调用不代表请求体检查成功，应遵循 Forward 指南的检查顺序。Gateway 会检查最终响应（含合成响应），但修改后的请求字节在到达源站前不会再次检查。选择流量前需了解：HTTPS 需要解密、WebSocket 绕过 Worker、匹配 Workers VPC 流量会被丢弃、Worker 调用失败时按失败关闭处理。

验证方式

针对已安装的 Gateway 类型做类型检查，并测试命名 RPC 入口，包括零次或一次续接调用及 Worker 使用的上下文值；再通过限定范围的 Gateway Forward 策略测试允许的请求。直接请求默认 fetch() 处理器不能验证 Gateway 路径，应遵循模板测试流程与 Forward 指南的排障步骤。响应与流式规则包括：返回 200 至 599 的最终状态；HEAD 请求及 204、205、304 状态不返回正文；流式传输正文而非缓冲。

技能介绍