部署完 API 中转站后,浏览器端报跨域错误,多数情况下不只是「没加 Access-Control-Allow-Origin」这么一条。真正要先分清的是:报错发生在浏览器里的 fetch/XHR 调用,还是 curl、后端服务之间的调用。后两者没有同源策略,出现 4xx 或连接失败属于另一类问题;只有浏览器发起、且协议、域名、端口任一不同,才会走 CORS 预检。判断清楚这一点,后面的排查方向才不会跑偏。
先确认报错来自浏览器跨域调用,再用 curl 复现 OPTIONS 预检看服务端实际返回了什么。跨域头建议只在一层输出:要么 Nginx 这类反向代理统一加,要么由应用框架中间件加,两层同时加容易出现重复头,浏览器会直接拒绝。改完的验证点是预检返回 2xx 且带齐 Allow-Origin、Allow-Methods、Allow-Headers,浏览器里同一条响应只出现一个 Allow-Origin。
先确认当前场景和目标
动手改配置前,先把下面几件事确认清楚,否则容易在错误的层反复调整。
- 调用方在哪:浏览器页面直连中转站域名,还是前端服务端转发。只有浏览器直连才需要考虑 CORS;服务端转发不存在跨域限制。
- 请求是否带凭证:如果用 cookie 或
credentials: 'include',响应头就不能用*,必须回显具体 Origin,并带上Vary: Origin。 - 链路有几层:浏览器 → CDN/WAF/负载均衡 → Nginx → 应用。任意一层都可能追加或覆盖跨域头,需要逐层确认。
- 跨域头由谁负责:先决定由反代还是应用框架输出。建议只选一层,另一层如果上游已经带了 Access-Control-* 头,用
proxy_hide_header去掉,避免重复。 - 目标是什么:浏览器能正常拿到业务响应体,而不是只让报错消失。预检通过但实际请求仍失败,通常是鉴权或头字段不对。
按这个顺序处理
第一步,用 curl 复现预检。不依赖浏览器,先看服务端到底怎么回 OPTIONS:
curl -i -X OPTIONS 'https://relay.example.com/v1/chat/completions' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: authorization,content-type'
如果返回 405、404,或者状态码正常但没有 Access-Control-Allow-Origin,说明预检请求被应用路由拦住了或者压根没处理,这就是主要矛盾。

第二步,在反代层补齐预检和实际响应的头。下面是一个可替换的 Nginx 片段,域名、上游地址按自己的环境改:
map $http_origin $cors_origin {
default "";
"~^https://app\.example\.com$" $http_origin;
"~^https://admin\.example\.com$" $http_origin;
}
server {
listen 443 ssl;
server_name relay.example.com;
location /v1/ {
if ($request_method = OPTIONS) {
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
add_header Access-Control-Max-Age 600 always;
return 204;
}
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Vary Origin always;
proxy_hide_header Access-Control-Allow-Origin;
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
}
}
白名单用 map 而不是直接写 *,是为了给后面加凭证留余地。proxy_hide_header 的作用是挡掉上游返回的同名头,防止浏览器收到两个 Allow-Origin。
第三步,如果要由应用层处理。中间件需要注册在鉴权、路由之前,并且 4xx/5xx 的错误响应也要走同一套头,否则前端在鉴权失败时看到的仍然是 CORS 报错。通用骨架大致是:先判断请求方法是否为 OPTIONS,是则直接返回 204 并附跨域头;不是则设置头之后继续交给后续处理链。
改完后怎么验证
- 再跑一次上面的 curl 预检命令,预期看到 204 或 200,且
Access-Control-Allow-Origin的值与请求 Origin 一致,方法头和请求头列表覆盖浏览器实际需要发送的字段。 - 在浏览器开发者工具的 Network 面板里看两条记录:预检 OPTIONS 和实际 POST。重点看实际请求的响应头中
Access-Control-Allow-Origin是否只有一条,出现两条基本就是两层都在加。 - 用一个最小页面发一次真实业务请求,确认拿到的是业务返回体而不是控制台报错,这比只看报错消失更可靠。
- 查看应用日志里是否出现过 OPTIONS 记录:如果预检在反代就被 204 拦下,应用日志里看不到属正常;如果本应是应用处理却完全没记录,说明请求根本没到达应用。
- 改配置后建议用无痕窗口或换个端口访问前端,避免浏览器缓存了上一次的预检结果。
容易忽略的边界
- Nginx 的 add_header 继承规则:当前层级一旦写了 add_header,就不再继承上一层的 add_header。在 if 块、location 块里分别写过之后,server 层的其他安全头可能一起失效,需要逐层核对。
- CDN 与网关会改写头:部分云厂商的 CDN、WAF 或负载均衡自带跨域配置,会追加一套头。Nginx 改对了但浏览器仍报重复,要往上排查一层。
- 预检不带业务凭证:OPTIONS 请求不会携带 Authorization 或 cookie,如果中转站的鉴权对所有方法生效,预检会直接 401,需要在鉴权中间件里放行 OPTIONS。
- 通配符与凭证互斥:带 cookie 的场景下
Access-Control-Allow-Origin: *一定无效,必须回显具体域名。 - 不适用的情况:如果调用方是服务端脚本、移动端原生请求或命令行工具,跨域头加了也没有作用,此时应查网络连通性、证书和鉴权。若短期内无法改反代配置,可以让前端同域部署一个转发路径指向中转站,这只是绕开浏览器同源限制的临时手段,不解决部署结构问题,也不应被当作性能优化。