函数常见问题

报错信息

HttpBody.constructor: invalid status code

报错原因

596、597、598、599均属于函数内部使用的响应状态码，禁止在代码中主动返回这些状态码。

报错信息

io error@: io error(Connection reset by peer)

报错原因

函数执行的时间超过了 CPU 时间规格限制，函数主动断开连接，函数虚拟机被中止，系统会生成错误日志。

2023 0306 16:39:39.611431 115939 JSThread-3() E @tag(JSError) @loc(src/js-instance-inl.h:366)]: <uid: debugger::I::79de2290-d3a3-4f89-81db-6c3ba779b8b2;event: fetch;host: ;path: /;auth: market.wapa.taobao.com;unique_id: ;pip: 127.0.0.1:46174;fetch_uuid: b5f59f33-8f9b-487d-be32-56e3c368f3f0;start_ts: 1678091979098;req: http;milestone: *-*---;><N/A><>: category: Fatal Error; caller: JSInstance; sub-reason: cpu time; description: N/A; message: the virtual machine has been forcebly terminated for user id 'debugger::I::79de2290-d3a3-4f89-81db-6c3ba779b8b2' due to its violation of resource constraints of system!

解决方法

调大 CPU 时间规格，例如从 50 ms 调整为 100 ms。

报错信息

unhandled error(13485,13477)@: Error: io error@: no available fetch proxy address now\nstacktrace:\nN/A\n

报错原因 1

在cache.put中 put 的是以https开头的 URL，由于 cache API 不支持https，需要将https改成http。

报错原因 2

fetch 请求的是一个非ESA的域名，但是设置了cdnProxy:true，需要将 fetch 的域名也接入ESA，或者删除cdnProxy:true配置。

报错信息

Error: unhandled error(13486,13505)@: Broken connection, unexpected EOF

报错原因

函数在接收源站返回的数据时，源站主动断开连接。

问题描述

使用函数处理请求后，通过ali-real-client-ip标头获取到的始终是内网 IP，而非客户端真实 IP。

原因分析

使用 fetch 模式时，函数作为中间代理向源站发起请求，源站收到的是函数运行环境的内网地址，因此ali-real-client-ip标头返回的是边缘节点内网 IP 而非客户端真实 IP。

解决方法

开启旁路模式，使请求不再经过函数处理，客户端 IP 不会被修改。详细操作请参见域名配置中的旁路模式章节。

fetch 模式与旁路模式的核心差异如下：

模式	真实 IP	适用场景
fetch 模式	返回内网 IP	需要函数修改响应内容（如压缩、改写）
旁路模式	返回客户端真实 IP	鉴权、日志打点等轻量场景

如需在函数代码中实现，可将入口从async fetch(request)改造为async bypass(request)。其中ResponseBypass是 ESA 函数运行环境提供的内置对象，用于控制请求是否绕过函数处理：

// 旁路模式入口函数
async bypass(request) {
  // 执行鉴权等前置逻辑
  const isAuthPassed = true; // 替换为实际鉴权逻辑

  if (isAuthPassed) {
    // 鉴权成功，返回 true 旁路处理响应
    return new ResponseBypass(true);
  } else {
    // 鉴权失败，返回 false 并指定失败状态码
    return new ResponseBypass(false, { status: 403 });
  }
}

验证方法

开启旁路模式后，可通过以下方式验证ali-real-client-ip标头是否返回客户端真实 IP：

• 使用 curl 命令检查响应头：

  curl -I https://your-domain.com

  在返回的响应头中查看ali-real-client-ip的值，应为客户端公网 IP 而非内网 IP。

• 通过浏览器开发者工具的 Network 面板查看响应头中的ali-real-client-ip值。

问题描述

在 ESA 边缘函数上部署 Vue + Vite 等单页应用（SPA）时，URL 路径末尾被自动追加斜杠（/），导致页面加载失败或路由异常。

原因分析

ESA 边缘函数默认以静态资源模式处理请求，未将路径识别为 SPA 路由，而是按目录结构追加尾随斜杠。SPA 的客户端路由依赖精确路径匹配，尾随斜杠改变了路径，导致路由无法命中。

解决方法

在项目根目录的 esa.jsonc 文件中，将 assets 参数配置为 singlePageApplication，使 ESA 以 SPA 模式处理请求路由。配置示例：

{
  "assets": "singlePageApplication"
}

配置完成后重新部署函数，ESA 将把所有路径请求回退到 index.html，由客户端路由接管，不再追加尾随斜杠。