可用上下文

Gateway 将 context 作为第二个参数传递给 GatewayMiddleware.handle(request, context, next)。上下文描述 Gateway 选择 Forward 策略 时的原始请求。修改 Request 不会更新上下文。

字段名称使用 camelCase。可选字段在不可用时会被省略，空的元数据列表也会被省略。可用性取决于连接方法、目标和已验证会话。使用可选值之前请先检查它们。

在 Worker 项目中安装 @cloudflare/zt-types ↗ 2026.10.1 或更高版本：

npm i -D @cloudflare/zt-types

yarn add -D @cloudflare/zt-types

pnpm add -D @cloudflare/zt-types

bun add -d @cloudflare/zt-types

对 Gateway 类型使用 import type，如示例和每个 Worker 模板所示。这些导入会在 TypeScript 编译时被移除，不会增加运行时依赖。JavaScript 示例省略类型导入和注解，不需要此软件包。该软件包导出以下 Gateway 类型：

context.uri 包含 scheme 和 authority。规范化会移除默认端口和片段、排序查询参数并规范化编码。它可能与 request.url 不同。对请求本身操作时使用 request.url，比较规范化元数据时使用 context.uri。

使用标准 Request API 访问方法、标头、cookie 和正文。上下文不包含自定义函数结果、DLP 匹配详细信息或原始内部设备记录。

仅当你的脚本需要与 Gateway 会话关联的身份时，才调用 await context.identity()。其返回类型为 Promise<GatewayIdentity | null>。

await 后的调用行为如下：

• 当用户已识别时返回身份对象。
• 没有已识别用户时返回 null。
• 如果 Gateway 无法检索身份，则抛出错误。

使用 Gateway 提供的身份进行感知用户的逻辑。客户端提供的身份标头不是权威替代。

检查缺失身份（!identity）以明确允许或拒绝匿名流量。

调用 await context.devicePosture() 以检索已通过的状况检查标识符：

{
	"checks": {
		"passed": ["<POSTURE_CHECK_UUID>"]
	}
}

checks.passed 是状况检查 UUID 的只读列表。空数组表示没有检查通过。当没有注册设备时，getter 解析为 { checks: { passed: [] } }。要求特定已通过检查的 Worker 必须拒绝此请求。

如果 Gateway 无法检索设备状况，await devicePosture() 会抛出错误。请将其与没有任何已通过检查的会话分开处理。

getter 不返回原始测试结果或失败检查列表。

即使 Gateway 无法检索身份或设备状况，仍会调用 Worker。如果任一 await 调用抛出错误且你的 Worker 未捕获该错误，Gateway 会返回 HTTP 500。

使用 try/catch 选择 Worker 如何处理这些错误。示例对检索错误返回 HTTP 503，在身份或所需状况检查缺失时返回 HTTP 403。

如果你的应用程序在 Gateway 无法检索身份或状况时有意允许流量，请从 catch 块返回 next(request)。这将在不要求缺失结果的情况下继续请求。

仅在调用 next() 之前使用此方法。每次调用最多调用一次 next()。

此脚本在继续之前要求身份电子邮件和特定已通过的状况检查。匿名流量和没有所需检查的设备会收到合成 403 响应。

身份或状况检索错误会收到 503。将 <POSTURE_CHECK_UUID> 替换为你账户中的检查。

import { WorkerEntrypoint } from "cloudflare:workers";

export class GatewayMiddleware extends WorkerEntrypoint {
	async handle(request, context, next) {
		try {
			const identity = await context.identity();
			if (!identity?.email) {
				return new Response(null, { status: 403 });
			}
			const passed = (await context.devicePosture())?.checks.passed ?? [];
			if (!passed.includes("<POSTURE_CHECK_UUID>")) {
				return new Response(null, { status: 403 });
			}
		} catch {
			return new Response(null, { status: 503 });
		}
		return next(request);
	}
}

import { WorkerEntrypoint } from "cloudflare:workers";
import type {
	GatewayMiddlewareContext,
	GatewayMiddlewareNext,
} from "@cloudflare/zt-types";

export class GatewayMiddleware extends WorkerEntrypoint {
	async handle(
		request: Request,
		context: GatewayMiddlewareContext,
		next: GatewayMiddlewareNext,
	): Promise<Response> {
		try {
			const identity = await context.identity();
			if (!identity?.email) {
				return new Response(null, { status: 403 });
			}
			const passed = (await context.devicePosture())?.checks.passed ?? [];
			if (!passed.includes("<POSTURE_CHECK_UUID>")) {
				return new Response(null, { status: 403 });
			}
		} catch {
			return new Response(null, { status: 503 });
		}
		return next(request);
	}
}

当可以使用内置身份选择器或设备状况选择器表达要求时，请在 Gateway 过滤策略中配置它。对需要自定义代码的要求使用 Worker 逻辑。

Gateway 用分号合并重复的 Cookie 标头，用逗号合并其他重复标头。Set-Cookie 值保留单独条目。使用 response.headers.getSetCookie() 读取各个响应 cookie。修改标头时，使用 new Headers(response.headers) 复制它们以保留其表示。