边缘开发者平台
  • 边缘函数
    • 概述
    • 快速指引
    • 操作指引
      • 函数管理
      • 触发配置
    • Runtime APIs
      • addEventListener
      • Cache
      • Cookies
      • Encoding
      • Fetch
      • FetchEvent
      • Headers
      • Request
      • Response
      • Streams
        • ReadableStream
        • ReadableStreamBYOBReader
        • ReadableStreamDefaultReader
        • TransformStream
        • WritableStream
        • WritableStreamDefaultWriter
      • Web Crypto
      • Web standards
      • Images
        • ImageProperties
    • 示例函数
      • 返回 HTML 页面
      • 返回 JSON
      • Fetch 远程资源
      • 请求头鉴权
      • 修改响应头
      • AB 测试
      • 设置 Cookie
      • 基于请求区域重定向
      • Cache API 使用
      • 缓存 POST 请求
      • 流式响应
      • 合并资源流式响应
      • 防篡改校验
      • m3u8 改写与鉴权
      • 图片自适应缩放
      • 图片自适应 WebP
      • 自定义 Referer 限制规则
      • 远程鉴权
      • HMAC 数字签名
      • 自定义下载文件名
      • 获取客户端 IP
    • 最佳实践
      • 通过边缘函数实现自适应图片格式转换
Docs Overview/
边缘开发者平台/
边缘函数/
Runtime APIs/
FetchEvent/

FetchEvent

FetchEvent 代表任何传入的 HTTP 请求事件，边缘函数通过注册 fetch 事件监听器实现对 HTTP 请求的处理。

描述

在边缘函数中，使用 addEventListener 注册 fetch 事件监听器，生成 HTTP 请求事件 FetchEvent ，进而实现对 HTTP 请求的处理。
注意：
不支持直接构造 FetchEvent 对象，使用 addEventListener 注册 fetch 事件获取 event 对象。
// event 为 FetchEvent 对象
addEventListener('fetch', (event) => {
  event.respondWith(new Response('hello world!'))；
});

属性

clientId

// event.clientId
readonly clientId: string;
边缘函数为每一个请求分配的 id 标识。

request

// event.request
readonly request: Request;
客户端发起的 HTTP 请求对象，详情参见 Request。

方法

respondWith

event.respondWith(response: Response | Promise<Response>): void;
边缘函数接管客户端的请求，并使用该方法，返回自定义响应内容。
注意：
事件监听器 addEventListener 的 fetch 事件回调中，需要调用接口 event.respondWith() 响应客户端，若未调用该接口，边缘函数会将当前请求转发回源站。

参数

参数名称
类型
必填
说明
response
Response | Promise<Response>
是
客户端 HTTP 请求的响应。

waitUntil

event.waitUntil(task: Promise<any>): void;
用于通知边缘函数等待 Promise 完成，可延长事件处理的生命周期。

参数

参数名称
类型
必填
说明
task
Promise<Response>
是
等待完成的 Promise 任务。

passThroughOnException

event.passThroughOnException(): void;
用于防止运行时响应异常信息。当函数代码抛出未处理的异常时，边缘函数会将此请求转发回源站，进而增强服务的可用性.

示例代码

未调用接口 event.respondWith，边缘函数将当前请求转发回源站。
function handleRequest(request) {
  return new Response('Edge Functions, Hello World!');
}

addEventListener('fetch', event => {
  const request = event.request;
  // 请求 url 包含字符串 /ignore/ ，边缘函数会将当前请求转发回源站。
  if (request.url.indexOf('/ignore/') !== -1) {
    // 未调用接口 event.respondWith
    return;
  }

  // 在边缘函数中，自定义内容响应客户端
  event.respondWith(handleRequest(request));
});
当函数代码抛出未处理的异常时，边缘函数会将此请求转发回源站。
addEventListener('fetch', event => {
  // 当函数代码抛出未处理的异常时，边缘函数会将此请求转发回源站 
  event.passThroughOnException();
  throw new Error('Throw error');
});

相关参考

MDN 官方文档：FetchEvent
示例函数：返回 HTML 页面
示例函数：Cache API 使用