代理约束与本地开发
同源代理接受哪些上游地址、如何校验来源，以及开发与预览服务器如何接入同一实现。
上游地址
代理不限制供应商域名，在网页中填写自定义 HTTPS API 地址即可使用，无需配置服务器环境变量。地址必须使用完整域名；不接受 IP 字面量、单标签主机名，以及 localhost、.local、.internal 域名。
代理只接受 HTTPS 的默认 443 端口、三种协议端点和不超过 128 KiB 的 JSON 请求。它不跟随重定向，不透传 Cookie 或任意请求头；客户端必须提供自己的上游密钥。
| 状态码 | 原因 |
|---|---|
| 400 | 请求体不是 JSON 对象、协议不支持、缺少模型，或上游地址不符合上述要求 |
| 401 | 缺少 Authorization: Bearer <key> |
| 403 | 跨站请求：Origin 与站点不同，或 Sec-Fetch-Site 不是同源 |
| 405 | 使用了 GET、POST、OPTIONS 以外的方法 |
| 413 | 请求体超过 128 KiB |
| 415 | 请求不是 application/json |
| 499 | 客户端取消了请求 |
| 502 | 上游返回重定向、成功状态但不支持的响应类型，或无法连接 |
| 504 | 上游 250 秒内没有响应 |
这些是代理自己的错误，响应体为 {"error":{"message":"…"}}。上游返回的 JSON 或 SSE 响应连同状态码原样转发，例如上游的 401 或 429；上游以错误状态返回其他类型的内容时，代理保留该状态码，只替换响应体。
同源代理的 Origin 与 Sec-Fetch-Site 校验限制浏览器跨站调用，但不替代站点鉴权或平台限流。自建 Worker 额外接受 ALLOWED_ORIGINS 中列出的跨域页面，见自建 Worker 代理。
本地开发
bun run dev 和 bun run preview 已接入同一代理，无需另外启动后端服务。这两个脚本在 Node 中运行代理，并设置 NODE_USE_ENV_PROXY=1：转发请求按 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 经本机代理发出，未设置这些变量时直接连接上游。本地 Pages 预览用 bun run preview:pages，运行在 http://127.0.0.1:8788；本地 Worker 用 bun run dev:worker，运行在 http://127.0.0.1:8787，由 workerd 运行，不读取这些变量。
CLI 不经过代理，总是直接连接上游，也接受 http:// 端点。
最后更新于