上午10点，前端同事在群里@我：“接口突然403了，昨天还好好的。”我查了Nginx日志，预检请求（OPTIONS）返回404。原因是运维在升级时不小心把处理OPTIONS的location块注释了。这不是偶然——CORS配置出问题的场景太常见，而且一错就全线崩溃。很多开发者觉得CORS很简单：后端加个Access-Control-Allow-Origin: *就完了。实际上，精细化配置涉及多个响应头字段的协同，稍有遗漏就会踩坑。
从一次线上事故说起：CORS配置不当导致的接口不可用
那次事故的根源是：我们允许了多个前端域名，但后端代码中写死了Allow-Origin: https://app.example.com，而新上线的另外一个子域名https://admin.example.com没有加入白名单。更糟的是，前端在fetch中加了credentials: 'include'，后端同时返回了Access-Control-Allow-Origin: *（实际上是另一个环境忘了改）。浏览器报错：“The value of the ‘Access-Control-Allow-Origin’ header in the response must not be the wildcard ‘*’ when the request’s credentials mode is ‘include’。”整个管理后台直接瘫掉。
你发现没有？CORS的“坑”往往藏在组合约束里：通配符与凭证模式不兼容、预检请求缓存时间设置不合理导致跨域报错、多个Vary头缺失导致浏览器缓存混乱。只有把每个响应头字段的语义和限制吃透，才能做精细化配置。
CORS的核心机制：你真正需要理解的是“浏览器策略”
CORS不是后端安全机制，而是浏览器强制实施的一种同源策略例外。服务器通过响应头告诉浏览器：“这个来源可以读取我的响应。”而预检请求是浏览器嗅探服务器是否“许可”那些非简单请求（比如PUT、DELETE、自定义头）。
记住：浏览器拦截的是响应，不是请求。请求实际上已经到达服务器并返回了响应，只是浏览器发现响应头不符合策略，把响应抛弃了，并在控制台报错。这个认知决定了排查方向——不要以为是后端没收到请求。
关键响应头字段拆解
Access-Control-Allow-Origin：不止是“*”那么简单
这是CORS最基础的字段，也是最容易被误用的。它的取值可以是：
- 单个域名：例如
https://app.example.com。如果有多个来源，不能直接写多个域名，需要动态根据Origin请求头来返回。 - 通配符
*：表示允许任何来源。但不能与Access-Control-Allow-Credentials: true同时使用，否则浏览器会拒绝。此外，通配符也不适用需要携带Cookie的场景。
实际生产中，如果是内部服务（如API网关），通常采用动态白名单：读取请求中的Origin，如果属于允许的域名列表，就原值返回；否则不设置该头或返回错误。注意：动态设置后必须加上Vary: Origin响应头，避免CDN或浏览器对不同的Origin缓存同一个响应。
Access-Control-Allow-Methods 与 Access-Control-Allow-Headers
这两个字段用于预检请求的响应，告知浏览器实际请求允许的HTTP方法和请求头。一个常见错误是：后端只配置了GET, POST，但前端发送了PUT或自定义头X-Requested-With，预检就会失败。建议：如果API设计涵盖了多种方法，直接列出所有支持的；头信息也一样，列出你实际会用到的。不要图省事写*，除非你能保证不涉及凭证模式且浏览器版本支持。
Access-Control-Allow-Credentials：Cookie跨域的关键开关
如果你需要让前端携带Cookie（比如Session ID）跨域请求，后端必须返回Access-Control-Allow-Credentials: true。同时，前端的fetch或XHR也要设置withCredentials: true（或credentials: ‘include’）。一旦开启凭证，Allow-Origin就不能是*，必须明确指定来源域名。而且，Access-Control-Allow-Headers和Access-Control-Allow-Methods也不能使用通配符（部分浏览器放宽了此限制，但为稳妥建议明确列出）。
Access-Control-Max-Age：减少预检请求的负担
预检请求每次都会发送一个OPTIONS请求，增加延迟。通过Access-Control-Max-Age可以告诉浏览器缓存预检结果多久（单位秒）。例如Access-Control-Max-Age: 86400表示缓存一天。设置过短会导致频繁预检，过长则可能导致策略变更后缓存未过期引发问题。推荐设置为600~3600秒（10分钟到1小时）。注意：浏览器有自己的最大上限（Chrome限制600秒），实际缓存时间以两者中较小的为准。
Access-Control-Expose-Headers：让前端读取自定义响应头
默认浏览器只暴露6个简单响应头（Cache-Control、Content-Language等）。如果后端返回了自定义头（如X-Total-Count），前端通过response.headers.get()无法获取。需要后端设置Access-Control-Expose-Headers: X-Total-Count。如果你希望前端能读取所有自定义头，可以用*（但注意不含Set-Cookie等）。
精细化配置实战：多环境、多域名、动态Origin
基于请求Origin动态返回Allow-Origin
以Node.js Express为例，你可以编写一个中间件：
const allowedOrigins = [
'https://app.example.com',
'https://admin.example.com',
'http://localhost:3000'
];
app.use((req, res, next) => {
const origin = req.headers.origin;
if (allowedOrigins.includes(origin)) {
res.setHeader('Access-Control-Allow-Origin', origin);
res.setHeader('Vary', 'Origin');
}
// 其他头
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
res.setHeader('Access-Control-Allow-Credentials', 'true');
res.setHeader('Access-Control-Max-Age', '3600');
if (req.method === 'OPTIONS') {
return res.sendStatus(204);
}
next();
});注意：OPTIONS请求要立即返回204，并且不携带其他业务逻辑。如果使用框架（如Spring Boot），也有类似Filter机制。
使用Nginx反向代理统一处理CORS
如果你的架构是Nginx代理到后端，可以将CORS配置下沉到Nginx层，避免代码重复。例如：
location /api/ {
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' '$http_origin' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
add_header 'Access-Control-Max-Age' 3600;
add_header 'Access-Control-Allow-Credentials' 'true';
add_header 'Vary' 'Origin';
return 204;
}
# 正常请求也需添加CORS头
add_header 'Access-Control-Allow-Origin' '$http_origin' always;
add_header 'Access-Control-Allow-Credentials' 'true';
add_header 'Vary' 'Origin';
proxy_pass http://backend;
}这里的$http_origin变量会获取请求的Origin头。配合map指令可以实现白名单：
map $http_origin $cors_origin {
default "";
"~^(https?://(app|admin).example.com)$" $1;
"~^http://localhost:3000$" $1;
}
server {
location /api/ {
if ($cors_origin != "") {
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Vary Origin;
}
# ... 其他头
}
}安全性考量：避免过度开放与CSRF风险
CORS不是防CSRF的。即使你精确限制了来源，攻击者仍然可以通过引导用户访问恶意站点，再通过表单提交（简单请求）来利用用户浏览器中的Cookie。所以不要仅依赖CORS来保护敏感接口。应结合CSRF Token、SameSite Cookie等机制。另外，不要轻易设置Access-Control-Allow-Origin: *且不对方法做限制——任何网站都可以发起跨域请求并读取响应，泄露数据风险高。推荐的做法：最小权限原则，只给实际需要跨域的域名授权；对不需要读响应数据的接口（如图片上传回调），可以考虑不返回CORS头，让浏览器自行处理。
验证与监控：如何快速定位CORS故障
当出现跨域问题时，不要盲目加头。优先查看浏览器控制台的具体错误信息：
- “No ‘Access-Control-Allow-Origin’ header is present on the requested resource”——说明服务器根本没返回该头。检查响应头列表。
- “The value of ‘Access-Control-Allow-Origin’ in the response must not be the wildcard ‘*’ when the request’s credentials mode is ‘include’”——通配符与凭证冲突。
- “Response to preflight request doesn’t pass access control check: It does not have HTTP ok status.”——OPTIONS请求返回了非2xx状态码。
- “Access-Control-Allow-Methods missing”或“Access-Control-Allow-Headers missing”——预检响应中缺少对应头。
用curl模拟预检请求是快速定位后端配置的手段：
curl -X OPTIONS -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Content-Type" -v https://api.example.com/data观察返回的响应头。如果本地正常而线上有CDN，可能还要检查CDN是否缓存了不带CORS头的响应（可通过Vary: Origin防止）。
总结：CORS配置清单
- 明确需要跨域的来源列表（不是通配符的情况下）；
- 开启Credentials时，Allow-Origin必须指定具体域名；
- 根据实际请求的方法和头，在预检响应中明确列出；
- 合理设置Max-Age（建议600~3600秒）；
- 动态Origin必须附带Vary: Origin；
- Nginx层统一管理时注意map指令过滤；
- 不要混淆CORS与CSRF，需要额外防护；
- 验证时用curl、Postman或浏览器控制台，查看实际响应头。
CORS配置看似琐碎，但遵循“最小开放、动态校验、凭证明确、缓存适度”的原则，就能避免大多数线上事故。下次再遇到跨域报错，先深呼吸，逐条检查响应头——少了哪条补哪条，但别忘了它们的组合约束。
延伸阅读