服务器Nginx CORS跨域配置如何匹配请求头并验证预检请求
浏览器出现“跨域请求被拦截”,不一定是 Nginx 没有返回 Access-Control-Allow-Origin。常见情况是:简单请求能到达接口,但带有 Authorization 或自定义请求头的请求先发出预检;Nginx虽然返回了 204,却没有在预检响应中允许浏览器请求的头部,实际请求因此根本没有发送。
排查时要把预检和实际请求分开看:预检响应中的 Access-Control-Allow-Headers 必须覆盖浏览器通过 Access-Control-Request-Headers 报出的请求头;实际响应也必须带有与来源匹配的跨域响应头。只检查状态码,或只在浏览器地址栏直接打开接口,都不能证明跨域配置有效。
概念边界:CORS检查的是浏览器跨域响应
CORS(跨源资源共享)是一套由浏览器执行的跨域访问规则。浏览器比较页面来源与接口来源,并根据响应中的 CORS 响应头,决定是否允许网页代码读取接口响应。来源由协议、主机和端口共同决定,例如 https://app.example.com 与 http://app.example.com 不是同一来源,端口不同也属于不同来源。
Nginx可以在响应中添加 CORS 响应头,也可以将预检请求直接返回;它不会因此替浏览器取消跨域限制。反过来,命令行工具即使收到接口响应,也不会像浏览器一样执行 CORS 校验。因此,curl 适合核对请求和响应头,浏览器则用于确认页面实际是否通过跨域检查。
CORS也不是接口鉴权机制。允许某个来源读取响应,不等于该来源获得了接口权限;未授权请求仍应由应用的登录、令牌和权限校验处理。配置时不要将“允许跨域”当作访问控制。
工作机制:先看预检,再看实际响应
浏览器遇到某些跨域请求时,会先发送 OPTIONS 预检请求。常见触发情形包括请求使用 Authorization 等非简单请求头,或使用 PUT、DELETE 等方法。预检通常包含以下请求头:

Origin: https://app.example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization,content-type,x-request-id
其中,Access-Control-Request-Headers 列出浏览器准备在实际请求中使用的请求头。Nginx或后端的预检响应需要允许相应的来源、方法和请求头,例如:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID
浏览器按规则检查这些响应头。请求头名称不区分大小写,因此 authorization 与 Authorization 表示同一请求头;但名称必须在允许列表中,不能因为配置了 Content-Type 就认为 Authorization 也已允许。
预检通过后,浏览器才发送实际请求。实际响应仍需包含适用于该来源的 Access-Control-Allow-Origin。如果请求使用凭据,响应还需包含 Access-Control-Allow-Credentials: true,且 Access-Control-Allow-Origin 不能是 *,必须返回具体来源。凭据场景还应确认前端请求确实启用了相应的凭据选项。
影响因素:配置在哪一层、响应由谁生成
CORS 响应头可能由 Nginx、上游应用或更前面的 CDN 添加。如果多个层同时添加 Access-Control-Allow-Origin,响应中可能出现重复或冲突的值,浏览器会拒绝处理。应先确定由哪一层统一负责,再检查响应中是否仍有另一层返回同名头部。
Nginx配置的作用范围也会影响结果。add_header 放在 http、server 或 location 中,作用范围不同;如果下级配置块自行定义了 add_header,它可能不会按预期继承上级的设置。排查时不要只看主配置文件,还要查看实际命中的 server 和 location,以及通过 include 引入的配置。

此外,Nginx的 add_header 默认只对部分响应状态生效。使用 always 可以让响应头也出现在其他状态码的响应中,但它只影响响应头是否添加,不代表请求头、来源或方法已通过 CORS 检查。若错误响应由上游生成,还要确认该响应是否经过预期的 Nginx配置块。
面向需要部署 Nginx 与接口服务的业务,A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,涵盖 Xeon、AMD EPYC 等平台及 SSD、NVMe 存储方案。不同地区和产品系列提供相应的线路与硬件配置,可为网站后台、数据库及 API 服务提供部署资源,也便于围绕业务服务所在层设计和管理跨域响应头。
示例配置:允许指定来源和请求头
下面示例假定 Nginx负责为 /api/ 添加 CORS 响应头,接口位于上游服务。示例只允许两个指定来源;实际使用时应替换为真实页面来源,并按接口需要调整方法和请求头。map 必须放在 http 配置块中,不能放进 server 或 location。
http {
map $http_origin $cors_origin {
default "";
https://app.example.com $http_origin;
https://admin.example.com $http_origin;
}
server {
listen 443 ssl;
server_name api.example.com;
location /api/ {
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Request-ID" always;
add_header Vary "Origin" always;
if ($request_method = OPTIONS) {
return 204;
}
proxy_pass http://api_upstream;
}
}
}
这段配置的关键点不在于 OPTIONS 是否返回 204,而在于预检响应同时带有正确的允许来源、允许方法和允许请求头。$cors_origin 只有在请求的 Origin 与映射项匹配时才有值;未列入映射的来源不会获得允许来源头。不要直接将任意 $http_origin 原样回显,否则任何来源都可能被允许。
如果接口需要跨域携带凭据,可以在确认来源为明确白名单后添加:
add_header Access-Control-Allow-Credentials "true" always;
此时不要把允许来源配置成 *。如果不需要跨域凭据,就不应为了消除报错而无条件添加该响应头。
Vary: Origin 用于提示缓存系统响应内容可能随 Origin 改变。若已有 Vary 响应头,应确认它与其他值能正确合并,避免覆盖缓存层需要的变化维度。若 CORS 由上游处理,则应核对 Nginx是否又重复添加了相关响应头;必要时明确只由一个层级负责。
配置中使用了 if 直接返回预检响应。修改后先检查语法,再按运维流程加载配置;不要在未确认目标实例和配置路径时直接操作服务:
nginx -t
只有检查通过后,才按当前系统的服务管理方式重新加载 Nginx。若配置不通过,应先修正语法或作用域问题,不要以强制重启代替检查。
验证方法:用请求头复现浏览器预检
验证应先确认请求是否到达预期的 Nginx,再分别检查预检和实际响应。以下请求模拟页面 https://app.example.com 准备以 PUT 方法发送三个请求头的情况:

curl -i -X OPTIONS 'https://api.example.com/api/items/123' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: PUT' \
-H 'Access-Control-Request-Headers: authorization,content-type,x-request-id'
重点核对响应中的状态码和头部:
- 状态码通常可为
204或其他成功响应;关键是浏览器收到的 CORS 响应头符合要求。 Access-Control-Allow-Origin应与允许的来源一致,不能缺失或出现多个冲突值。Access-Control-Allow-Methods应包含请求预期使用的方法,例如PUT。Access-Control-Allow-Headers应覆盖authorization、content-type和x-request-id。名称大小写不同通常不构成问题。- 若页面请求携带凭据,响应还应包含
Access-Control-Allow-Credentials: true,且允许来源不能是*。
接着用同一来源发送实际请求,检查实际响应是否也包含正确的 Access-Control-Allow-Origin。示例请求可能触发应用鉴权并返回 401;这不必然表示 CORS 配置失败,但若浏览器需要读取该错误响应,错误响应同样要带上适用的 CORS 响应头。
curl -i -X PUT 'https://api.example.com/api/items/123' \
-H 'Origin: https://app.example.com' \
-H 'Authorization: Bearer example-token' \
-H 'Content-Type: application/json' \
-H 'X-Request-ID: test-123' \
--data '{"name":"sample"}'
还应使用未列入白名单的来源重复预检,例如:
curl -i -X OPTIONS 'https://api.example.com/api/items/123' \
-H 'Origin: https://other.example.net' \
-H 'Access-Control-Request-Method: PUT' \
-H 'Access-Control-Request-Headers: authorization'
如果该来源不在允许列表中,响应不应把它作为允许来源回显。服务器返回 204 并不等于该来源通过 CORS;浏览器还会检查响应头。若不允许的来源仍收到匹配的 Access-Control-Allow-Origin,应检查是否由上游、CDN或其他 Nginx配置块添加了响应头。
curl 不执行浏览器的 CORS拦截逻辑。它能证明服务器收到了哪些请求头、返回了哪些响应头,却不能单独证明浏览器会放行。最终还需在浏览器开发者工具的网络面板中查看 OPTIONS 和实际请求:如果只有 OPTIONS 而没有后续请求,优先检查预检的允许来源、方法和请求头;如果实际请求已发出但页面仍报跨域错误,检查实际响应及错误状态响应中的 CORS头部。

适用限制:预检成功不代表接口请求成功
预检只是在浏览器发送实际请求之前核对跨域规则,不验证令牌有效性、用户权限、请求参数或业务状态。预检返回成功后,实际请求仍可能因鉴权、路由、上游故障或应用校验失败而返回错误。排查时应区分“浏览器是否允许读取响应”和“接口是否成功处理请求”这两类问题。
如果预检响应正常但浏览器仍拦截,不要只增加更多允许头部。先比较浏览器发出的 Access-Control-Request-Headers 与预检响应,再确认实际响应是否带有对应的来源头、是否出现重复响应头,以及请求是否被转发到了另一组 Nginx配置或上游服务。反之,如果 OPTIONS 返回非成功状态,检查该请求是否被鉴权规则、方法限制、上游路由或其他中间层提前拒绝。
CORS配置应与接口实际使用的来源、方法和请求头对应。只有在预检与实际响应都符合浏览器检查规则时,才能判断跨域配置有效;命令行返回成功、接口能直接访问,或单独看到 204,都不足以替代这两项验证。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5069.html



