Nginx 工程实践 -- 23. CORS 跨域配置

前后端分离、第三方嵌入、本地开发联调,都会撞上浏览器的同源策略。CORS 的响应头谁都能加,但预检(OPTIONS)怎么处理、带凭证时 * 为什么失效、Vary 为什么必须加,这些细节一错就是"浏览器报 CORS 错误、后端日志却一片正常"。

flowchart TD
    A["跨站请求"] --> B{"是否预检?"}
    B -->|"简单请求"| C["直接发请求"]
    B -->|"需预检"| D["先 OPTIONS"]
    D --> E{"Nginx 返回
Allow-Methods / Headers / Origin?"} E -->|"不满足"| F["浏览器拦截"] E -->|"满足"| C C --> G["响应带
Access-Control-Allow-Origin"]

一、简单请求与预检

浏览器把跨域请求分两类:

  • 简单请求:方法为 GET/HEAD/POST,且头字段在安全列表内(如 Accept、Content-Type: application/x-www-form-urlencoded 等),直接发送,响应头里带 Access-Control-Allow-Origin 即可;
  • 预检请求:用了 PUT/DELETE、自定义头、application/json 等情况,浏览器先发 OPTIONS,等 Nginx 返回允许的方法/头/来源后,才发真正的请求。

所以 Nginx 侧要做两件事:响应加 ACAO,以及处理 OPTIONS 预检。

二、响应加 CORS 头

1
2
3
4
5
6
7
8
location /api/ {
proxy_pass http://backend;

add_header Access-Control-Allow-Origin $http_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 86400 always;
}
  • always 很重要:默认 add_header 只在 200/201/204/206/301/302/303/304/307/308 时生效,4xx/5xx 不带;CORS 头要在错误响应上也存在,否则浏览器仍拦截;
  • Access-Control-Allow-Origin 用 $http_origin 回显来源(动态),或按需写白名单变量(见下)。

三、处理 OPTIONS 预检

预检请求不该打到后端,直接在网关返回:

1
2
3
4
5
6
7
8
9
10
11
12
13
location /api/ {
proxy_pass http://backend;

if ($request_method = OPTIONS) {
add_header Access-Control-Allow-Origin $http_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 86400 always;
return 204;
}

add_header Access-Control-Allow-Origin $http_origin always;
}

也可以把预检交给一个 location = /api/options 或用 limit_except,但 if + return 204 是最直观的一种。

四、带凭证(Cookie / Authorization)

一旦前端 withCredentials: true 或带 Authorization,Access-Control-Allow-Origin 不能是 *,必须回显具体来源,并加:

1
add_header Access-Control-Allow-Credentials true always;
  • * + credentials 会被浏览器拒绝;
  • Allow-Methods/Allow-Headers 里的 * 在带凭证时同样受限;
  • 来源白名单建议用 map 收敛(见第 20 篇):
1
2
3
4
5
6
7
8
9
10
11
map $http_origin $cors_origin {
default "";
~^https://(www\.)?example\.com$ $http_origin;
~^http://localhost:\d+$ $http_origin;
}
server {
location /api/ {
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Credentials true always;
}
}

五、Vary: Origin

当 CORS 头是按 Origin 动态生成(回显或白名单)时,响应内容随 Origin 变化。若前面有缓存(CDN、proxy_cache),必须加:

1
add_header Vary Origin always;

否则不同来源可能拿到带错误 Allow-Origin 的缓存副本,出现"换个域名就不行"的诡异问题。

六、常见坑

坑说明
响应头不加 always错误响应没有 CORS 头,浏览器仍拦截
带凭证用 *浏览器直接拒绝,必须回显具体来源
没处理 OPTIONS预检 405/404,真实请求从不被发出
动态 Origin 没加 Vary缓存串味,不同来源拿到错误头
if 里 proxy_passif 内推荐 return/rewrite,别做复杂逻辑(见第 14 篇)
来源白名单写死用 map 收敛,避免正则散落
只在 server 加头注意 add_header 的继承覆盖规则(子级定义会覆盖父级同名头)

参考链接

  1. MDN:Cross-Origin Resource Sharing (CORS) —— 简单请求、预检与响应头语义;
  2. Nginx 官方文档:ngx_http_headers_module(add_header) —— always 参数;
  3. Nginx 官方文档:ngx_http_core_module(add_header 继承) —— 层级继承规则;
  4. Nginx 官方文档:ngx_http_map_module —— 来源白名单;
  5. Fetch 标准:CORS 协议。

小结

  • 简单请求只需 Access-Control-Allow-Origin;预检要先答 OPTIONS;
  • add_header ... always 保证错误响应也带 CORS 头;
  • 带凭证时 * 失效,必须回显具体来源 + Allow-Credentials;
  • 动态 Origin 必须加 Vary: Origin;
  • 来源白名单用 map 收敛,if 里只做 return。

系列导航


Nginx 工程实践 -- 23. CORS 跨域配置
https://bubao.github.io/posts/b3c4d5e6.html
作者
一念
发布于
2026年11月21日
许可协议