Nginx配置CORS必须为所有add_header指令添加always参数，否则OPTIONS预检响应缺失CORS头导致跨域失败；应避免if+proxy_pass混用，改用两个有序location分别处理预检和转发；Credentials为true时Access-Control-Allow-Origin不可为*，需动态匹配可信域名；proxy_set_header仅影响后端请求，add_header always才控制浏览器响应头。
add_header 必须加 always 参数，否则 OPTIONS 响应里没有 CORS 头
浏览器对 POST、PUT 或带 Authorization 头的请求，会先发一次 OPTIONS 预检。如果你只写 add_header 'Access-Control-Allow-Origin' '*'，Nginx 默认只在成功响应（2xx/3xx）里加这个头，而 if ($request_method = 'OPTIONS') { return 204; } 是一个无 body 的响应，不触发默认的 header 注入逻辑——结果就是浏览器收不到任何 CORS 头，直接报错。
正确做法是所有 add_header 后都加上 always：
add_header 'Access-Control-Allow-Origin' '*' always;add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Requested-With' always;add_header 'Access-Control-Max-Age' 1728000 always;
不加 always 是线上最常被忽略的配置错误，重启后测试 curl -I -X OPTIONS http://your-api.com/api/，确认响应头里真有这些字段。
不要用 if + proxy_pass 混合处理，避免 502 和 header 丢失
常见错误写法是在同一个 location 块里既写 if ($request_method = 'OPTIONS') 又写 proxy_pass：
location /api/ {
if ($request_method = 'OPTIONS') {
add_header ... always;
return 204;
}
proxy_pass http://backend;
}
这种结构在 Nginx 里属于“非标准上下文”，if 块内不能安全使用 proxy_pass，且部分版本会丢掉 proxy_set_header 设置，导致后端收不到 Host 或 X-Real-IP，返回 502。
推荐拆成两个独立 location：
- 一个专用于拦截
OPTIONS：用location /api/+if+return 204，只负责预检 - 另一个用于转发真实请求：用
location /api/（同路径）+proxy_pass，不加if
注意：两个 location 必须顺序明确，且 if 块必须在 proxy_pass 块之前，否则 Nginx 会按字典序匹配，OPTIONS 可能被转发给后端。
Access-Control-Allow-Credentials 为 true 时，Access-Control-Allow-Origin 不能是 *
如果前端设置了 credentials: 'include'（比如要传 cookie 或 token），后端（或 Nginx）就必须同时满足两个条件：
add_header 'Access-Control-Allow-Credentials' 'true' always;-
add_header 'Access-Control-Allow-Origin' 'https://your-frontend-domain.com' always;（不能用*）
违反任一条件，浏览器就直接拒绝响应。常见踩坑点是开发环境用 * 测试没问题，上线后开了 credentials 却忘了改 Origin，结果只有登录态相关的接口失败。
若需多域名支持，得用 map 模块动态匹配，例如：
map $http_origin $cors_origin {
https://fe.example.com https://fe.example.com;
https://staging.fe.example.com https://staging.fe.example.com;
default "";
}
server {
location /api/ {
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' $cors_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
return 204;
}
add_header 'Access-Control-Allow-Origin' $cors_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
}
}
反向代理场景下，别把 proxy_set_header 和 add_header 搞混
这是最隐蔽的误配点：proxy_set_header 是给后端发请求时加的头，浏览器完全看不到；add_header 才是加给浏览器的响应头，决定跨域是否通过。
典型错误：
- 把
Access-Control-Allow-Origin写成proxy_set_header Access-Control-Allow-Origin '*'→ 浏览器收不到，无效 - 漏掉
always，又没在if块里显式加头 →OPTIONS响应空空如也 - 在
proxy_pass后加add_header，但没加always→ 正常请求有头，OPTIONS还是没有
记住：跨域校验只看浏览器收到的响应头，而那个头只能靠 add_header ... always 来稳定注入。
