Request

Request ↗ 接口表示 HTTP 请求，是 Fetch API 的一部分。

最常见遇到 Request 对象的方式是作为传入请求的属性：

export default {
	async fetch(request, env, ctx) {
		return new Response('Hello World!');
	},
};

当你需要修改请求对象时，也可能需要自行构造 Request，因为从 fetch() handler 接收的传入 request 参数是不可变的。

export default {
	async fetch(request, env, ctx) {
        const url = "https://example.com";
        const modifiedRequest = new Request(url, request);
		// ...
	},
};

fetch() handler 调用 Request 构造函数。下面定义的 RequestInit 和 RequestInitCfProperties 类型也描述了可传递给 fetch() handler 的有效参数。

let request = new Request(input, options)

• input string | Request

  • 包含 URL 的字符串，或现有的 Request 对象。

• options options optional

  • 可选的 options 对象，包含要应用于 Request 的设置。

包含要应用于请求的属性的对象。

• cache undefined | 'no-store' | 'no-cache' optional

  • 标准 HTTP cache 头。仅支持 cache: 'no-store' 和 cache: 'no-cache'。 任何其他 cache 头将导致 TypeError，消息为 Unsupported cache mode: <attempted-cache-mode>。

• cf RequestInitCfProperties optional

  • 可在 Request 上设置的 Cloudflare 特定属性，控制 Cloudflare 全球网络如何处理请求。

• method stringoptional

  • HTTP 请求方法。默认为 GET。在 Workers 中，除 CONNECT ↗ 外，支持所有 HTTP 请求方法 ↗。

• headers Headers optional

  • Headers 对象 ↗。

• body string | ReadableStream | FormData | URLSearchParams optional

  • 请求 body（如有）。
  • 注意，使用 GET 或 HEAD 方法的请求不能有 body。

• redirect stringoptional

  • 要使用的重定向模式：follow、error 或 manual。新 Request 对象的默认值为 follow。但是，请注意 FetchEvent 的传入 Request 属性的重定向模式为 manual。

• signal AbortSignal optional

  • 如果提供，可以通过在相应的 AbortController 上触发 abort 来取消请求。

包含可在 Request 对象上设置的 Cloudflare 特定属性的对象。例如：

// Disable ScrapeShield for this request.
fetch(event.request, { cf: { scrapeShield: false } })

cf 对象中无效或命名不正确的键将被静默忽略。考虑使用 TypeScript 并通过运行 wrangler types 生成类型，以确保正确使用 cf 对象。

• apps booleanoptional

  • 是否应为此请求启用 Cloudflare Apps ↗。默认为 true。

• cacheEverything booleanoptional

  • 将所有内容视为静态，并缓存超出 Cloudflare 默认缓存内容的所有文件类型。遵循源 Web 服务器的缓存头。这相当于设置 Page Rule Cache Level（缓存级别） 为 Cache Everything（全部缓存）。默认为 false。 此选项仅适用于 GET 和 HEAD 请求方法。

• cacheKey stringoptional

  • 请求的 cache key 决定两个请求在缓存目的上是否相同。如果请求与之前的某个请求具有相同的 cache key，Cloudflare 可以为两者提供相同的缓存响应。

• cacheTags Array<string> optional

  • 此选项将额外的 Cache-Tag 头附加到来自源站服务器的响应。这允许根据 Worker 提供的标签清除缓存内容，而无需修改源站服务器。这是使用 Purge by Tag 功能实现的。

• cacheTtl numberoptional

  • 此选项强制 Cloudflare 缓存此请求的响应，无论响应上看到什么头。这相当于设置两个 Page Rule：Edge Cache TTL 和 Cache Level（缓存级别） 为 Cache Everything（全部缓存）。值必须为零或正数。值为 0 表示缓存资源立即过期。此选项仅适用于 GET 和 HEAD 请求方法。

• cacheTtlByStatus { [key: string]: number } optional

  • 此选项是 cacheTtl 功能的变体，根据响应的状态码选择 TTL。如果对此请求的响应具有匹配的状态码，Cloudflare 将按指示的时间缓存并覆盖源站发送的缓存指令。例如：{ "200-299": 86400, "404": 1, "500-599": 0 }。值可以是任何整数，包括零和负整数。值为 0 表示缓存资源立即过期。任何负值指示 Cloudflare 完全不缓存。此选项仅适用于 GET 和 HEAD 请求方法。

• vary RequestInitCfPropertiesVaryoptional

  • 控制 Cloudflare 如何为单个 fetch() 请求缓存带有 Vary 头的源站响应。如果 cf.vary 和 Cache Rules Vary 都适用，cf.vary 对此子请求优先。

• image Object | null optional

  • 为此请求启用 Image Resizing。可能的值在 Transform images via Workers 文档中描述。

• polish stringoptional

  • 设置 Polish ↗ 模式。可能的值为 lossy、lossless 或 off。

• resolveOverride stringoptional

  • 通过覆盖 DNS 查找将请求定向到备用源站服务器。resolveOverride 的值指定在确定源 IP 地址时使用的备用主机名，而不是使用 URL 中指定的主机名。请求的 Host 头仍将匹配 URL 中的内容。因此，resolveOverride 允许将请求发送到与 URL / Host 头指定的不同的服务器。但是，只有当 URL 主机和 resolveOverride 指定的主机都在你的 zone 内时，resolveOverride 才会生效。如果任一方指定了来自不同 zone / 域的主机，出于安全原因该选项将被忽略。如果你需要将请求定向到 zone 外的主机（同时保持 Host 头指向 zone 内），请先在 zone 内创建指向外部主机的 CNAME 记录，然后将 resolveOverride 设置为指向该 CNAME 记录。请注意，出于安全原因，除非请求实际发送到该主机，否则无法将 Host 头设置为 zone 外的主机。

• scrapeShield booleanoptional

  • 如果此 zone 另有配置，是否应为此请求启用 ScrapeShield ↗。默认为 true。

• webp booleanoptional

  • 在 Polish 中启用或禁用 WebP ↗ 图像格式。

cf.vary 对象控制 Cloudflare 如何处理单个 fetch() 请求的源 Vary 响应头中命名的请求头。它使用与 Cache Rules Vary 相同的 default 和 headers 结构，以及与 Vary 相同的操作和规范化行为。

如果省略 cf.vary，Cloudflare 将使用 zone 的其他 Vary 行为，包括已配置的 Cache Rules Vary。

源站响应必须包含 Vary 头，此设置才会影响 cache key。包含 Vary: * 的响应始终绕过缓存。

cf.vary 对象支持以下键：

如果存在 vary 对象，则 default 是必需的。空的 vary 对象无效。无效的 cf.vary 配置对该请求将被忽略。

每个头配置对象以及 default 对象必须包含 action 键，设置为 normalize、passthrough 或 bypass 之一。有关指导，请参阅操作。

可以为某些头名称指定额外参数：

default 对象以及 accept 和 accept-language 以外的 headers 条目仅支持 action。

对于大多数部署，将 default.action 设为 bypass，为预期的源 Vary 头添加 headers 条目，并对 accept 和 accept-language 使用 normalize，除非源站需要原始头值。

以下限制和验证规则适用：

• headers 中的头名称必须为小写。
• 头名称可包含小写字母、数字、下划线和连字符。
• 头名称不能超过 128 个字符。
• 以 cf- 或 cf_ 开头的头名称不允许。
• 不允许某些逐跳、缓存控制或代理控制头。示例包括 connection、content-length、cache-control、host、range、origin 和 x-forwarded-for。
• headers 最多可包含 50 个条目。
• accept.media_types 最多可包含 10 个条目。
• accept-language.languages 最多可包含 20 个条目。
• media_types 和 languages 中的值必须是非空可打印 ASCII 字符串。

以下 request init 片段规范化 Accept 和 Accept-Language，并对源 Vary 响应中的任何其他头绕过缓存：

{
	"cf": {
		"vary": {
			"default": {
				"action": "bypass"
			},
			"headers": {
				"accept": {
					"action": "normalize",
					"media_types": ["text/html", "application/json"]
				},
				"accept-language": {
					"action": "normalize",
					"languages": ["en", "fr", "de"]
				}
			}
		}
	}
}

传入 Request 对象（从 fetch() handler 接收的请求）的所有属性都是只读的。要修改传入请求的属性，请创建新的 Request 对象，并将要修改的 options 传递给其构造函数。

• body ReadableStream read-only

  • body 内容的流。

• bodyUsed Boolean read-only

  • 声明 body 是否已在响应中使用。

• cf IncomingRequestCfProperties read-only

  • 包含 Cloudflare 全球网络提供的有关传入请求信息的对象。
  • 此属性是只读的（除非从现有 Request 创建）。要修改其值，在创建新 Request 对象时通过 init options 参数的 cf 键 传入新值。

• headers Headers read-only

  • Headers 对象 ↗。

  • 与浏览器相比，Cloudflare Workers 对允许发送的头限制很少。例如，浏览器不允许设置 Cookie 头，因为浏览器负责自行处理 cookie。但是，Workers 对 cookie 没有特殊理解，将 Cookie 头视为任何其他头。

• method string read-only

  • 包含请求的方法，例如 GET、POST 等。

• redirect string read-only

  • 要使用的重定向模式：follow、error 或 manual。如果重定向模式设为 follow，fetch 方法将自动跟随重定向。如果设为 manual，3xx 重定向响应将按原样返回给调用方。新 Request 对象的默认值为 follow。但是，请注意 FetchEvent 的 Request 属性的重定向模式为 manual。

• signal AbortSignal read-only

  • 与此请求对应的 AbortSignal。如果使用 enable_request_signal 兼容性标志，可以向 signal 附加事件监听器。这允许你在 Worker 调用结束之前执行清理任务或写入日志。 例如，如果你运行下面的 Worker，然后从客户端 abort 请求，将写入日志：
    export default {
    	async fetch(request, env, ctx) {
    		// 这将设置一个事件监听器，如果客户端从您的 Worker 断开连接，该监听器将被调用。
    		request.signal.addEventListener("abort", () => {
    			console.log("The request was aborted!");
    		});
    
    		const { readable, writable } = new IdentityTransformStream();
    		sendPing(writable);
    		return new Response(readable, {
    			headers: { "Content-Type": "text/plain" },
    		});
    	},
    };
    
    async function sendPing(writable) {
    	const writer = writable.getWriter();
    	const enc = new TextEncoder();
    
    	for (;;) {
    		// 每秒发送 'ping' 以保持连接处于活动状态
    		await writer.write(enc.encode("ping\r\n"));
    		await scheduler.wait(1000);
    	}
    }

    export default {
      async fetch(request, env, ctx): Promise<Response> {
        // 这将设置一个事件监听器，如果客户端从您的 Worker 断开连接，该监听器将被调用。
        request.signal.addEventListener('abort', () => {
          console.log('The request was aborted!');
        });
    
        const { readable, writable } = new IdentityTransformStream();
        sendPing(writable);
        return new Response(readable, { headers: { 'Content-Type': 'text/plain' } });
      },
    } satisfies ExportedHandler<Env>;
    
    async function sendPing(writable: WritableStream): Promise<void> {
    	const writer = writable.getWriter();
    	const enc = new TextEncoder();
    
    	for (;;) {
    		// 每秒发送 'ping' 以保持连接处于活动状态
    		await writer.write(enc.encode('ping\r\n'));
    		await scheduler.wait(1000);
    	}
    }

• url string read-only

  • 包含请求的 URL。

除了标准 Request ↗ 对象上的属性外，入站 Request 上的 request.cf 对象包含 Cloudflare 全球网络提供的有关请求的信息。

所有套餐均可访问：

• asn Number

  • 传入请求的 ASN，例如 395747。

• asOrganization string

  • 拥有传入请求 ASN 的组织，例如 Google Cloud。

• botManagement Object | null

  • 仅在使用 Cloudflare Bot Management 时设置。包含以下属性的对象：score、verifiedBot、signedAgent、staticResource、ja3Hash、ja4 和 detectionIds。有关更多详情，请参阅 Bot Management Variables。

• clientAcceptEncoding string | null

  • 如果 Cloudflare 替换了 Accept-Encoding 头的值，原始值存储在 clientAcceptEncoding 属性中，例如 "gzip, deflate, br"。

• clientQuicRtt number | undefined

  • Cloudflare 与客户端之间 QUIC 连接的平滑往返时间（RTT），以毫秒为单位。仅在客户端通过 QUIC（HTTP/3）连接时存在。例如 42。

• clientTcpRtt number | undefined

  • 客户端与 Cloudflare 之间 TCP 连接的平滑往返时间（RTT），以毫秒为单位。仅在客户端通过 TCP（HTTP/1 和 HTTP/2）连接时存在。例如 22。

• colo string

  • 请求到达的数据中心的 IATA ↗ 三字机场代码，例如 "DFW"。

• country string | null

  • 传入请求的国家/地区。请求中的两字母国家/地区代码。这与 CF-IPCountry 头提供的值相同，例如 "US"。

• edgeL4 Object | undefined

  • 客户端与 Cloudflare 之间连接的 Layer 4 传输统计。包含以下属性：
    • deliveryRate number - 连接的最新数据传输速率估计，以字节/秒为单位。例如 123456。

• isEUCountry string | null

  • 如果传入请求的国家/地区在欧盟，将返回 "1"。否则，此属性被省略或为 false。

• httpProtocol string

  • HTTP 协议，例如 "HTTP/2"。

• hostMetadata Object | undefined

  • 仅在传入请求来自具有自定义主机名元数据的 zone 时填充。有关可添加为自定义主机名元数据 的内容以及如何在 hostMetadata 字段上暴露的更多信息，请参阅 Cloudflare for Platforms 文档。

• requestPriority string | null

  • 请求对象中浏览器请求的分优先级信息，例如 "weight=192;exclusive=0;group=3;group-weight=127"。

• tlsCipher string

  • 与 Cloudflare 连接的密码，例如 "AEAD-AES128-GCM-SHA256"。

• tlsClientAuth Object | null

  • 有关客户端证书的各种详情（用于 mTLS 连接）。有关更多详情，请参阅客户端证书变量。

• tlsClientCiphersSha1 string

  • TLS 握手期间客户端发送的密码套件的 SHA-1 哈希（Base64 编码），以大端格式编码。例如 "GXSPDLP4G3X+prK73a4wBuOaHRc="。

• tlsClientExtensionsSha1 string

  • TLS 握手期间发送的 TLS 客户端扩展的 SHA-1 哈希（Base64 编码），以大端格式编码。例如 "OWFiM2I5ZDc0YWI0YWYzZmFkMGU0ZjhlYjhiYmVkMjgxNTU5YTU2Mg=="。

• tlsClientExtensionsSha1Le string

  • TLS 握手期间发送的 TLS 客户端扩展的 SHA-1 哈希（Base64 编码），以小端格式编码。例如 "7zIpdDU5pvFPPBI2/PCzqbaXnRA="。

• tlsClientHelloLength string

  • TLS 握手 ↗ 中发送的 client hello 消息的长度。例如 "508"。具体而言，client hello 的字节串长度。

• tlsClientRandom string

  • TLS 握手 ↗ 中客户端提供的 32 字节随机值。有关更多详情，请参阅 RFC 8446 ↗。

• tlsVersion string

  • 与 Cloudflare 连接的 TLS 版本，例如 TLSv1.3。

• city string | null

  • 传入请求的城市，例如 "Austin"。

• continent string | null

  • 传入请求的大洲，例如 "NA"。

• latitude string | null

  • 传入请求的纬度，例如 "30.27130"。

• longitude string | null

  • 传入请求的经度，例如 "-97.74260"。

• postalCode string | null

  • 传入请求的邮政编码，例如 "78701"。

• metroCode string | null

  • 传入请求的 metro 代码（DMA），例如 "635"。

• region string | null

  • 如果已知，与传入请求 IP 地址关联的第一级区域的 ISO 3166-2 ↗ 名称，例如 "Texas"。

• regionCode string | null

  • 如果已知，与传入请求 IP 地址关联的第一级区域的 ISO 3166-2 ↗ 代码，例如 "TX"。

• timezone string

  • 传入请求的时区，例如 "America/Chicago"。

这些方法仅在 Request 对象实例上或通过其原型可用。

• clone() : Request

  • 创建 Request 对象的副本。

• arrayBuffer() : Promise<ArrayBuffer>

  • 返回一个 promise，解析为请求 body 的 ArrayBuffer ↗ 表示。

• formData() : Promise<FormData>

  • 返回一个 promise，解析为请求 body 的 FormData ↗ 表示。

• json() : Promise<Object>

  • 返回一个 promise，解析为请求 body 的 JSON 表示。

• text() : Promise<string>

  • 返回一个 promise，解析为请求 body 的字符串（文本）表示。

每次 Worker 被传入 HTTP 请求调用时，fetch() handler 会在 Worker 上调用。Request 上下文在调用 fetch() handler 时开始，异步任务（例如使用 fetch() API 发起子请求）只能在 Request 上下文内运行：

export default {
	async fetch(request, env, ctx) {
        // Request context starts here
		return new Response('Hello World!');
	},
};

如果你将 Response promise 传递给 fetch event 的 .respondWith() 方法，在 Response promise settle 之前运行的任何异步任务期间，Request 上下文处于活跃状态。你可以将 event 传递给 async handler，例如：

addEventListener("fetch", event => {
  event.respondWith(eventHandler(event))
})

// No request context available here

async function eventHandler(event){
  // Request context available here
  return new Response("Hello, Workers!")
}

在脚本启动期间尝试使用 fetch() 等 API 或访问 Request 上下文将抛出异常：

const promise = fetch("https://example.com/") // Error
async function eventHandler(event){..}

此代码片段将在脚本启动期间抛出，"fetch" 事件监听器将永远不会注册。

Content-Length 头将由运行时根据 Request 的数据源自动设置。用户在 Headers 中手动设置的任何值都将被忽略。要指定具有特定值的 Content-Length 头，Request 的 body 必须是 FixedLengthStream 或固定长度值（如字符串或 TypedArray）。

FixedLengthStream 是一个 identity TransformStream，仅允许向其写入固定数量的字节。

  const { writable, readable } = new FixedLengthStream(11);

  const enc = new TextEncoder();
  const writer = writable.getWriter();
  writer.write(enc.encode("hello world"));
  writer.end();

  const req = new Request('https://example.org', { method: 'POST', body: readable });

使用任何其他类型的 ReadableStream 作为请求的 body 将导致使用 Chunked-Encoding。

Workers 对 Request 接口的实现包含对 Web 标准 Request API 的多项扩展。这些差异是有意为之，提供 Workers 运行时特有的额外功能。

Workers 向 Request 对象添加 cf 属性，其中包含有关传入请求的 Cloudflare 特定元数据。此属性不是 Web 标准的一部分，仅在 Workers 运行时中可用。有关详情，请参阅 IncomingRequestCfProperties。

headers 属性返回 Workers 特定的 Headers 对象，包含 getAll() 等用于 Set-Cookie 头的额外方法。有关 Workers Headers 实现与 Web 标准差异的详情，请参阅 Headers 文档。

传递给 fetch() handler 的传入 Request 对象是不可变的。要修改传入请求的属性，必须创建新的 Request 对象。

• Examples: Modify request property
• Examples: Accessing the cf object
• Reference: Response
• 使用 ES modules 语法 编写 Worker 代码以获得优化体验。