Edge Workers 概览与快速入门

Edge Workers 是运行在 CDN 边缘节点上的 JavaScript 函数。请求到达边缘、通过安全检查之后、查询缓存和回源之前，匹配到路由的 Worker 会先执行，它可以：

• 直接响应：返回自定义内容或重定向，请求不再回源；
• 改写回源请求：追加/覆盖请求头（也可改写请求方法和路径）后继续回源；
• 放行：不做任何改动，按域名原有配置处理。

编程模型参考 Cloudflare Workers：导出 export default { fetch(request, env, ctx) }，返回 Response 对象。每次执行都在全新的隔离沙箱中进行，不同请求之间不共享任何全局状态。

#控制台入口

#快速入门

#第 1 步：创建 Worker

1. 进入 CDN管理 → Workers，点击右上角 创建Worker。
2. 填写 名称（必填）和 描述（可选）。
3. 在 从模板开始（可选） 下拉框中可以选择一个示例模板（如「自定义响应」「重定向」「鉴权」「Crypto 工具箱」「Fetch 透传」）载入编辑器，也可以直接粘贴下面的示例代码。
4. 确认 启用 开关为打开状态，点击 保存更改。

保存成功后页面会跳转到该 Worker 的详情页，顶部显示版本号；每次修改代码后保存，版本号会自动加一。

#第 2 步：编写代码

下面是一个最小可用示例：访问 /hello 时由边缘直接返回 JSON，其余路径放行回源。

export default {
  async fetch(request, env, ctx) {
    // request.url 可能是 "/hello?x=1"，也可能是完整 URL，这里统一取出路径部分
    const path = request.url.replace(/^https?:\/\/[^\/]+/, "").split("?")[0];

    if (path === "/hello") {
      return Response.json({
        message: "Hello from the edge",
        host: request.headers.get("host"),
        method: request.method,
      });
    }

    // 不处理的请求：放行，按域名原有配置回源
    return { action: "continue" };
  },
};

#第 3 步：绑定到域名

1. 进入 CDN管理 → 域名管理，打开目标域名，切换到 Worker 标签页。
2. 点击 添加绑定，在弹窗中：
   • 选择Worker：选择刚创建的 Worker（只列出已启用的 Worker）；
   • 路由模式：例如 /hello，或 /* 匹配全部路径（规则见下文）；
   • 优先级：0–999，数值越大越优先；
   • 启用：保持打开。
3. 点击 保存。配置会自动下发到边缘节点，通常很快生效。

#第 4 步：测试

curl -i https://www.example.com/hello

返回 200 和上面的 JSON 即表示 Worker 已生效；访问其他路径应与绑定前的行为一致。

#编程接口

#入口

推荐写法是 export default { fetch(request, env, ctx) { ... } }，fetch 可以是同步函数，也可以是 async 函数。平台同时兼容 export default function (request) {} 以及全局函数 function handler(request) {}。

#request 对象

#返回值

例如，为回源请求打上 A/B 分组标记：

export default {
  fetch(request) {
    const cookie = request.headers.get("cookie") || "";
    const m = /ab_bucket=(A|B)/.exec(cookie);
    const bucket = m ? m[1] : (Math.random() < 0.5 ? "A" : "B");
    return { action: "rewrite", headers: { "x-ab-bucket": bucket } };
  },
};

#可用的全局 API

• fetch(url, init)：向公网 HTTP/HTTPS 地址发起子请求，返回 Promise<Response>，可读取 status、ok、headers、text()、json()；可直接 return fetch(url) 把结果作为响应返回。
• Headers、Request、Response、TextEncoder / TextDecoder、btoa / atob。
• crypto.subtle.digest、crypto.subtle.importKey / sign / verify（HMAC）、crypto.getRandomValues、crypto.randomUUID，以及便捷函数 crypto.md5()、crypto.sha1()、crypto.sha256()、crypto.hmac()（返回十六进制字符串）。

fetch 子请求的限制：

• 只允许 http/https，目标端口仅限 80 和 443；
• 内网、环回、链路本地等私有地址一律拒绝；
• 最多跟随 3 次重定向，单个子请求超时 10 秒，响应体上限 8 MiB。

#路由模式

路由模式只匹配请求的路径（不含域名和查询串），并且要求与整个路径完全匹配：

• * 匹配任意字符（包括 /，可跨多级目录）；** 与 * 效果相同；
• ? 匹配单个字符；
• 留空或填 *、/* 匹配所有路径。

每个请求最多只执行一个 Worker：多条绑定同时匹配时，只运行优先级数值最大的那一条。请给可能重叠的绑定设置不同的优先级。

#资源限制

#出错时的行为与调试

Worker 抛出异常、语法错误、超时或超出资源限制时，平台采用放行策略：这次请求会像没有绑定 Worker 一样按原配置回源，而不是返回错误页。因此如果请求没有得到预期结果，请先检查代码是否能正常运行。

#启用、禁用与删除

• 在 Workers 列表中 禁用 某个 Worker 后，它在所有域名上都停止执行；单条绑定也可以在域名的 Worker 标签页中单独禁用。
• 删除 Worker 会让所有绑定了它的域名停止执行该 Worker。
• 修改代码并保存后，所有绑定了该 Worker 的域名会自动更新。

#套餐与配额

每个域名可添加的 Worker 路由（绑定）数量由该域名关联的 CDN 套餐决定。撰写本文时，CDN 起步版、专业版、企业版均为每个域名 5 条，具体以套餐页面为准。达到上限后再添加绑定会提示「已达 Worker 路由上限」，需要升级套餐或删除已有绑定。

#通过 API 管理

控制台的操作都对应用户 API，请求需携带登录令牌 Authorization: Bearer <token>：

# 创建 Worker（带 id 字段即为更新）
curl -X POST https://api.yeap.cloud/api/user/cdn/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"hello","code":"export default { fetch(){ return new Response(\"hi\"); } };","enabled":true}'

# 绑定到域名
curl -X POST https://api.yeap.cloud/api/user/cdn/domains/www.example.com/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"worker_id":123,"route_pattern":"/hello","priority":10,"enabled":true}'

其他接口：GET /api/user/cdn/workers（列表）、GET /api/user/cdn/workers/detail?id=（详情含代码）、POST /api/user/cdn/workers/toggle、DELETE /api/user/cdn/workers/delete（JSON 体 {"id":...}）；域名绑定：GET /api/user/cdn/domains/<域名>/workers、POST .../workers/toggle、DELETE .../workers/delete。

#当前不支持

• 读取请求体；
• 在控制台为 Worker 配置环境变量或 KV（env 为空对象）；
• 改写源站返回的响应（模板中的「响应头改写」目前不会生效，如需添加响应头请使用域名的规则功能）；
• ctx.waitUntil() 中的后台任务不保证在响应返回后继续执行；
• 运行日志与在线调试。