OPTIONS预检必须显式拦截并return 204,因Nginx默认不处理该方法且add_header不加always参数时仅对含body的2xx/3xx响应生效,无法注入到204响应中;所有CORS头均需加always,且应拆分location避免if与proxy_pass混用。

OPTIONS 预检请求必须显式拦截并 return 204,否则浏览器收不到 CORS 头,直接报错“No 'Access-Control-Allow-Origin' header is present”
为什么 add_header 不加 always 就失效
Nginx 的 add_header 默认只对 2xx/3xx 响应生效,且会跳过 return 204 这类无 body 的响应路径。即使 204 属于 2xx,Nginx 内部逻辑仍不注入 header——结果就是预检响应空有状态码,没有 Access-Control-Allow-Origin 等任何头。
- 错误写法:
add_header 'Access-Control-Allow-Origin' '*';(return 204时完全不生效) - 正确写法:
add_header 'Access-Control-Allow-Origin' '*' always;(所有状态码都强制注入) - 所有 CORS 相关的
add_header都要加always:包括Access-Control-Allow-Methods、Access-Control-Allow-Headers、Access-Control-Max-Age - 验证方式:
curl -I -X OPTIONS http://your-api.com/api/,确认响应头里真有这些字段
不能在同一个 location 里混用 if 和 proxy_pass
这种结构是 Nginx 的“非标准上下文”,会导致 proxy_set_header 丢失、后端收不到 Host 或 X-Real-IP,最终返回 502;更糟的是,部分版本会直接忽略 if 块里的 add_header。
- 错误写法:
if ($request_method = 'OPTIONS') { return 204; }和proxy_pass http://backend;写在同一location块内 - 正确做法:拆成两个
location,顺序不能错——先匹配 OPTIONS 的location,再写转发的location - 示例顺序:
location /api/ { if ($request_method = 'OPTIONS') { ... return 204; } }必须出现在location /api/ { proxy_pass http://backend; }之前,否则 Nginx 按字典序匹配,OPTIONS 可能被转发给后端
Access-Control-Allow-Origin 能不能用 *
取决于前端是否设置了 credentials: 'include'(比如带 Cookie 或 Authorization header)。如果用了,Access-Control-Allow-Origin 就不能是 *,否则浏览器直接拒绝响应。
- 若需支持凭据,必须指定具体域名:
add_header 'Access-Control-Allow-Origin' 'https://fe.example.com' always; - Nginx 原生不支持在
add_header中动态插值(如$http_origin),要用map模块提前定义白名单 - 同时要配
add_header 'Access-Control-Allow-Credentials' 'true' always;,且后端响应也得带对应 header - 注意缓存问题:加
add_header 'Vary' 'Origin' always;,避免 CDN 或代理缓存错 Origin 的响应
最常被忽略的其实是 always 参数和 location 拆分——这两个点没做对,其他配置再全也没用。尤其上线前务必用 curl -I -X OPTIONS 实测预检响应头是否完整。


















