gateway-workers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gateway Workers

Read the current Forward guide before implementing a Worker. It defines how Gateway invokes Workers on permitted HTTP traffic. Retrieve the relevant page below rather than copying setup, API payloads, or limits into the project from memory.

在实现 Worker 前，请阅读当前的 Forward 指南。该指南定义了 Gateway 如何在允许的 HTTP 流量上调用 Worker。请从下方获取相关页面，不要凭记忆将配置、API 载荷或限制复制到项目中。

Workflow

工作流

Inspect the existing Worker and choose a Worker template for the required transformation, synthetic response, or background task.
Export a named
```
GatewayMiddleware
```
class extending
```
WorkerEntrypoint
```
from
```
cloudflare:workers
```
. Implement
```
handle(request, context, next)
```
and return a
```
Response
```
. Gateway calls this method through RPC. A default
```
fetch()
```
handler alone does not implement the Forward contract.
For TypeScript, follow the chosen template's current package installation and type-import instructions.
Use the second argument for Gateway context. It describes the original request and stays unchanged when the Worker modifies the request. Keep it distinct from
```
this.ctx
```
(Workers execution context) and
```
this.env
```
(bindings).
Continue the user's request with
```
next(request)
```
at most once, or return a synthetic response without calling it.
```
next()
```
always targets the original destination. Changes to the destination URL or host are ignored, and it cannot redirect, retry, or fan out. Use
```
fetch()
```
to send a request to a different destination. It creates an independent subrequest that does not inherit the user's Gateway policies or egress configuration.

检查现有 Worker，并为所需的转换、合成响应或后台任务选择一个 Worker 模板。
导出一个命名的
```
GatewayMiddleware
```
类，该类继承
```
cloudflare:workers
```
中的
```
WorkerEntrypoint
```
。实现
```
handle(request, context, next)
```
并返回
```
Response
```
。Gateway 通过 RPC 调用此方法。仅使用默认的
```
fetch()
```
处理器无法实现 Forward 契约。
对于 TypeScript，请遵循所选模板当前的软件包安装和类型导入说明。
使用第二个参数获取 Gateway 上下文。它描述原始请求，并且当 Worker 修改请求时仍保持不变。务必将其与
```
this.ctx
```
（Workers 执行上下文）和
```
this.env
```
（绑定项）区分开来。
最多调用一次
```
next(request)
```
以继续处理用户请求，或者在不调用它的情况下返回合成响应。
```
next()
```
始终指向原始目标位置。对目标 URL 或主机所做的更改会被忽略，并且它无法重定向、重试或进行扇出。若要向其他目标发送请求，请使用
```
fetch()
```
。它会创建一个独立的子请求，不会继承用户的 Gateway 策略或出口配置。

Context

上下文

Use the published types and context reference for field names and availability. Treat a falsy identity (

!identity

) as anonymous and guard optional posture values. Call

await context.identity()

await context.devicePosture()

only when needed. Both getters can reject. Catch lookup failures separately from missing values and decide how to handle each when the Worker depends on them. Use Gateway-provided identity rather than client-supplied identity headers.

请使用已发布的类型和上下文参考来确认字段名称和可用性。将假值的身份（

!identity

）视为匿名身份，并对可选的姿态值进行判空保护。仅在需要时调用

await context.identity()

或

await context.devicePosture()

。两个 getter 都可能拒绝（reject）。应将查询失败与值不存在分开捕获，并在 Worker 依赖这些值时决定各自的处理方式。使用 Gateway 提供的身份信息，而不是客户端提供的身份标头。

Gateway behavior

Gateway 行为

Only the first matching Forward policy invokes a Worker. Worker invocation does not confirm successful body inspection. Follow the Forward guide's inspection order.
Gateway inspects the final response, including synthetic responses. Modified request bytes are not inspected again before reaching the origin.
Review the Forward guide's limitations before choosing traffic: HTTPS requires decryption, WebSockets bypass the Worker, and matching Workers VPC traffic is dropped. Worker invocation failures fail closed.

只有第一个匹配的 Forward 策略会调用 Worker。调用 Worker 并不表示正文检查已成功完成。请遵循 Forward 指南中的检查顺序。
Gateway 会检查最终响应，包括合成响应。修改后的请求字节在到达源站前不会再次接受检查。
在选择流量之前，请查阅 Forward 指南中的限制：HTTPS 需要解密，WebSockets 会绕过 Worker，与规则匹配的 Workers VPC 流量会被丢弃。Worker 调用失败时将采用 fail closed（失败即阻断）策略。

Validation

验证

Type-check against the installed Gateway types and test the named RPC entrypoint, including zero or one continuation call and the context values the Worker uses. Then test a permitted request through a scoped Gateway Forward policy. A direct request to a default

fetch()

handler does not validate the Gateway path. Follow the chosen template's test procedure and the Forward guide's troubleshooting steps.

Check the response and streaming rules: return a final status from

, return no body for HEAD requests or statuses

, and

, and stream bodies rather than buffering them.

根据已安装的 Gateway 类型进行类型检查，并测试命名的 RPC 入口点，包括零次或一次续接调用，以及 Worker 使用的上下文值。然后，通过限定范围的 Gateway Forward 策略测试一个允许的请求。直接向默认的

fetch()

处理器发起请求无法验证 Gateway 路径。请遵循所选模板的测试流程和 Forward 指南中的故障排查步骤。

请检查响应和流式传输规则：返回

到

范围内的最终状态码；对于 HEAD 请求或状态码为

、

和

的响应，不返回正文；应以流式方式传输正文，而不是对其进行缓冲。

gateway-workers

Original

Translation

Gateway Workers

Gateway Workers

Workflow

工作流

Context

上下文

Gateway behavior

Gateway 行为

Validation

验证

Related skills

相关 skill