Linux下Nginx跨域OPTIONS配置详解

本文深入剖析了Linux下Nginx配置CORS跨域时最易踩坑的四大核心问题：必须为所有add_header指令添加always参数，否则OPTIONS预检响应将缺失关键CORS头导致跨域失败；严禁在同一个location中混用if与proxy_pass，应拆分为两个有序location分别处理预检和转发，避免502错误与请求头丢失；当启用credentials时，Access-Control-Allow-Origin不可为*，需通过map模块动态匹配可信前端域名；最后强调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 来稳定注入。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~