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 | |
always很重要:默认add_header只在 200/201/204/206/301/302/303/304/307/308 时生效,4xx/5xx 不带;CORS 头要在错误响应上也存在,否则浏览器仍拦截;Access-Control-Allow-Origin用$http_origin回显来源(动态),或按需写白名单变量(见下)。
三、处理 OPTIONS 预检
预检请求不该打到后端,直接在网关返回:
1 | |
也可以把预检交给一个 location = /api/options 或用 limit_except,但 if + return 204 是最直观的一种。
四、带凭证(Cookie / Authorization)
一旦前端 withCredentials: true 或带 Authorization,Access-Control-Allow-Origin 不能是 *,必须回显具体来源,并加:
1 | |
*+ credentials 会被浏览器拒绝;Allow-Methods/Allow-Headers里的*在带凭证时同样受限;- 来源白名单建议用
map收敛(见第 20 篇):
1 | |
五、Vary: Origin
当 CORS 头是按 Origin 动态生成(回显或白名单)时,响应内容随 Origin 变化。若前面有缓存(CDN、proxy_cache),必须加:
1 | |
否则不同来源可能拿到带错误 Allow-Origin 的缓存副本,出现"换个域名就不行"的诡异问题。
六、常见坑
| 坑 | 说明 |
|---|---|
响应头不加 always | 错误响应没有 CORS 头,浏览器仍拦截 |
带凭证用 * | 浏览器直接拒绝,必须回显具体来源 |
| 没处理 OPTIONS | 预检 405/404,真实请求从不被发出 |
| 动态 Origin 没加 Vary | 缓存串味,不同来源拿到错误头 |
if 里 proxy_pass | if 内推荐 return/rewrite,别做复杂逻辑(见第 14 篇) |
| 来源白名单写死 | 用 map 收敛,避免正则散落 |
只在 server 加头 | 注意 add_header 的继承覆盖规则(子级定义会覆盖父级同名头) |
参考链接
- MDN:Cross-Origin Resource Sharing (CORS) —— 简单请求、预检与响应头语义;
- Nginx 官方文档:ngx_http_headers_module(add_header) ——
always参数; - Nginx 官方文档:ngx_http_core_module(add_header 继承) —— 层级继承规则;
- Nginx 官方文档:ngx_http_map_module —— 来源白名单;
- 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
