1. 项目概述从单域名到多域名的CORS策略演进如果你在开发前后端分离的Web应用特别是涉及到多个子域名、多个环境开发、测试、生产或者需要为第三方提供API服务时十有八九会在浏览器的开发者工具控制台里见过这个熟悉的红色错误“Access to fetch at ‘https://api.example.com‘ from origin ‘https://app.example.com‘ has been blocked by CORS policy”。这个问题的核心就是跨源资源共享CORS策略。而解决这个问题的关键就在于服务器端正确设置Access-Control-Allow-Origin这个响应头。简单来说Access-Control-Allow-Origin就像一道门卫它告诉浏览器“我允许来自哪些‘源’Origin即协议域名端口的网页来访问我的资源。” 最省事的做法是设置一个星号*表示允许所有源访问。但这样做安全性太低相当于大门敞开任何网站都能调用你的API容易引发CSRF等安全问题。因此在生产环境中我们几乎总是需要精确指定一个或多个允许的源。当你的服务只需要允许一个固定域名访问时配置很简单直接写上那个域名就行。但现实情况往往更复杂你的前端应用可能部署在app.example.com管理后台在admin.example.com移动端H5页面在m.example.com甚至还有本地开发的localhost:3000。这时你就需要让Access-Control-Allow-Origin支持多个域名。然而这个响应头在HTTP规范中只能设置一个值你不能直接写成https://app.example.com, https://admin.example.com。如何优雅、安全且高效地解决这个“一对多”的匹配问题就是本篇文章要深入探讨的核心。2. CORS核心机制与多域名挑战解析在深入解决方案之前我们必须先理解CORS机制特别是浏览器在发起跨域请求时的完整“握手”流程。这能帮助我们明白为什么简单的静态列表行不通以及后续各种方案的底层逻辑。2.1 简单请求与预检请求CORS将请求分为两类“简单请求”和“需预检的请求”。判断标准主要看请求方法、头部和Content-Type。简单请求例如使用GET、POST、HEAD方法且Content-Type为application/x-www-form-urlencoded、multipart/form-data或text/plain。对于这类请求浏览器会直接发出并在响应中检查Access-Control-Allow-Origin头。如果匹配当前页面的源则允许访问响应数据否则抛出CORS错误。需预检的请求当请求使用了PUT、DELETE方法或Content-Type为application/json或设置了自定义头部如Authorization,X-API-Key时浏览器会先发起一个OPTIONS方法的“预检请求”。这个请求的目的是询问服务器“我打算用这些方法、这些头部从某个源发起一个真实请求你允许吗” 服务器必须在预检请求的响应中通过Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers等头部明确告知允许的范围。只有预检请求通过后浏览器才会发出真实的请求。注意很多同学在调试时发现POST请求也报CORS错误很可能就是因为Content-Type是application/json触发了预检流程但服务器没有正确处理OPTIONS请求。2.2 多域名配置的核心矛盾Access-Control-Allow-Origin响应头只能包含一个源origin或者一个星号*。这是HTTP协议的规定。这就产生了一个矛盾我们的服务需要动态地、根据请求的来源返回一个与之匹配的、单一的值。例如一个请求来自https://app.example.com我们希望响应头是Access-Control-Allow-Origin: https://app.example.com另一个请求来自https://admin.example.com我们希望响应头变成Access-Control-Allow-Origin: https://admin.example.com。服务器必须有能力在运行时动态判断请求头中的Origin值并将其与一个允许的列表进行匹配。2.3 动态匹配的必要性与Vary头由于响应头Access-Control-Allow-Origin的值会根据请求头Origin的不同而动态变化我们必须通知浏览器和中间缓存如CDN、代理服务器这个资源的响应是“可变”的它依赖于Origin请求头。这是通过设置Vary: Origin响应头来实现的。Vary: Origin告诉缓存系统“在缓存这个响应时请将Origin请求头的值作为缓存键的一部分。” 这样来自app.example.com的请求得到的响应包含Access-Control-Allow-Origin: https://app.example.com会被单独缓存不会错误地返回给来自admin.example.com的请求。忘记设置Vary: Origin是导致多域名CORS配置下缓存混乱和随机错误的常见原因。3. 主流多域名CORS配置方案实战理解了原理我们来看具体怎么实现。根据你的技术栈和部署环境有几种主流方案。3.1 方案一后端动态判断与设置最灵活通用这是最经典、控制粒度最细的方案。核心逻辑是在服务器端代码中获取请求头中的Origin值与一个预定义的白名单列表进行匹配。如果匹配成功则将该Origin值设置到Access-Control-Allow-Origin响应头中否则可以返回一个错误或者不设置该头导致浏览器CORS错误。3.1.1 Node.js (Express) 示例const express require(express); const app express(); // 允许的源白名单 const allowedOrigins [ https://app.example.com, https://admin.example.com, https://m.example.com, http://localhost:3000, http://localhost:8080 ]; // CORS中间件 app.use((req, res, next) { const origin req.headers.origin; // 检查请求来源是否在白名单中 if (allowedOrigins.includes(origin)) { res.header(Access-Control-Allow-Origin, origin); // 动态设置为请求来源 res.header(Vary, Origin); // 关键告知缓存此响应随Origin变化 res.header(Access-Control-Allow-Credentials, true); // 如果需要携带Cookie等凭证 res.header(Access-Control-Allow-Headers, Content-Type, Authorization, X-Requested-With); res.header(Access-Control-Allow-Methods, GET, POST, PUT, DELETE, OPTIONS); } // 处理预检请求 if (req.method OPTIONS) { return res.sendStatus(200); } next(); }); // 你的API路由 app.get(/api/data, (req, res) { res.json({ message: Hello CORS! }); }); app.listen(3000);实操要点白名单管理建议将allowedOrigins列表放到环境变量或配置文件中便于不同环境开发、测试、生产进行管理。Credentials处理如果前端请求需要携带Cookies或HTTP认证信息必须设置Access-Control-Allow-Credentials: true并且Access-Control-Allow-Origin不能为通配符*必须是具体的域名。同时前端在发起请求时如使用Fetch API也需要设置credentials: include。OPTIONS预检中间件中显式处理OPTIONS方法并返回200可以确保预检请求快速通过。有些CORS中间件库会帮你自动处理。3.1.2 Nginx反向代理配置如果你的后端服务不方便修改代码或者你想在基础设施层统一管理CORSNginx是一个绝佳选择。server { listen 80; server_name api.yourdomain.com; # 定义允许的源支持正则表达式 map $http_origin $cors_origin { default ; ~^https?://(app|admin|m)\.example\.com$ $http_origin; ~^http://localhost:\d$ $http_origin; } location / { # 动态设置CORS头 if ($cors_origin ! ) { add_header Access-Control-Allow-Origin $cors_origin always; add_header Vary Origin always; add_header Access-Control-Allow-Credentials true always; add_header Access-Control-Allow-Methods GET, POST, OPTIONS, PUT, DELETE always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; } # 处理预检请求 if ($request_method OPTIONS) { add_header Access-Control-Max-Age 1728000; # 缓存预检结果20天 add_header Content-Type text/plain; charsetutf-8; add_header Content-Length 0; return 204; } proxy_pass http://your_backend_server; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }注意事项add_header与always参数Nginx的add_header指令在错误响应如4xx, 5xx时默认不添加头。使用always参数确保在所有响应中都会添加CORS头这对于错误处理的统一性很重要。Access-Control-Max-Age这个头用于指定预检请求结果可以被缓存的时间秒。设置一个合理的值如7200秒/2小时可以减少不必要的预检请求提升性能。但请注意如果CORS策略变更需要等待缓存过期或客户端清理。正则表达式匹配map指令中的正则表达式提供了灵活的匹配能力可以轻松匹配一类域名如所有子域名。3.2 方案二使用成熟的中间件/库快速集成大多数现代Web框架都有成熟的CORS中间件它们封装了动态匹配、预检处理等细节。Node.js/Express:cors包 (npm install cors)const cors require(cors); const allowedOrigins [https://app.example.com, http://localhost:3000]; app.use(cors({ origin: function (origin, callback) { // 允许没有Origin头的请求如移动端App、curl if (!origin) return callback(null, true); if (allowedOrigins.indexOf(origin) -1) { return callback(new Error(CORS policy: Origin not allowed), false); } return callback(null, origin); // 动态返回匹配的origin }, credentials: true, optionsSuccessStatus: 200 // 一些老设备IE11兼容 }));Python/Flask:flask-corsfrom flask import Flask from flask_cors import CORS app Flask(__name__) CORS(app, origins[https://app.example.com, http://localhost:3000], supports_credentialsTrue)Java/Spring Boot: 在配置类中定义CorsFilter或使用CrossOrigin注解。Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); CorsConfiguration config new CorsConfiguration(); config.setAllowCredentials(true); config.addAllowedOriginPattern(*); // Spring Boot 2.4 使用模式匹配更安全 // 或者 config.setAllowedOrigins(Arrays.asList(https://app.example.com)); config.addAllowedHeader(*); config.addAllowedMethod(*); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }使用库的优缺点优点快速集成经过充分测试通常能处理边缘情况如Vary头、预检缓存。缺点可能隐藏了一些底层细节当需要高度定制化或排查复杂问题时需要深入阅读其文档和源码。3.3 方案三Origin通配符与正则匹配的陷阱与慎用你可能会想既然允许多个子域名能不能用通配符比如*.example.com答案是Access-Control-Allow-Origin头本身不支持通配符子域名。你不能设置Access-Control-Allow-Origin: *.example.com浏览器会视其为无效值。但是在一些后端框架的配置项中你可能会看到支持“通配符模式”或“正则表达式”的选项如上面Spring Boot的addAllowedOriginPattern(*)。这实际上是框架在背后帮你做了动态的字符串匹配而不是浏览器直接支持通配符。其原理等同于我们方案一中的动态判断。需要极其警惕的是使用过于宽松的通配符如*或.*会带来严重的安全风险特别是在允许携带凭证Credentials时。请始终将允许的源列表限制在最小必要范围。4. 高级场景与深度优化策略解决了基本的多域名问题后我们还会遇到一些更复杂的场景需要更精细的策略。4.1 区分环境与动态白名单在实际开发中不同环境开发、测试、预发布、生产的允许源列表是不同的。硬编码在代码里显然不可取。最佳实践环境变量配置将白名单列表配置为环境变量用分隔符如逗号、分号连接。# .env 文件 ALLOWED_ORIGINShttps://app.example.com,https://admin.example.com,http://localhost:3000然后在你的服务器代码或Nginx配置中读取并解析这个环境变量。更动态的方案数据库或配置中心对于SaaS平台或需要让客户自助添加允许域名的场景可以将白名单存储在数据库或配置中心如Consul, Apollo。在中间件中每次请求时或定时缓存从这些动态源读取并检查。此时需要注意性能务必添加缓存层。4.2 预检请求的性能优化预检请求OPTIONS会增加一次额外的网络往返对性能有影响尤其是对于高频的API调用。设置Access-Control-Max-Age如前所述这个头告诉浏览器可以将预检请求的结果缓存多久。对于稳定不变的CORS策略可以设置一个较长的时间如12小时43200。尽可能使用简单请求在设计API时如果可能考虑使用符合简单请求条件的格式如将JSON数据通过FormData发送使用application/x-www-form-urlencoded。但这通常受限于业务需求。在Nginx/CDN层缓存OPTIONS响应对于静态资源或CORS策略长期不变的API可以在Nginx或CDN配置中直接缓存对OPTIONS方法的响应进一步减轻后端压力。4.3 携带凭证Cookies、认证信息的复杂情况当请求需要携带凭证时规则更加严格服务器必须设置Access-Control-Allow-Credentials: true。服务器的Access-Control-Allow-Origin不能是通配符*必须是明确的、与请求Origin完全匹配的域名。前端发起请求时必须设置withCredentials标志Fetch API:credentials: includejQuery:xhrFields: { withCredentials: true }Axios:withCredentials: true。一个常见坑点即使你的Access-Control-Allow-Origin是动态匹配的正确域名但如果响应中包含了Access-Control-Allow-Origin: *的缓存由于未正确设置Vary: Origin浏览器也会因为*与credentials: include不兼容而拒绝请求。这再次强调了Vary: Origin的重要性。4.4 非浏览器环境与移动端AppCORS是浏览器的安全策略。对于服务器对服务器的通信如curl、Postman、后端微服务间调用或者移动端App使用WebView或网络库如OkHttp、Alamofire它们默认不强制执行CORS检查。这意味着你的API在这些环境下可能“正常工作”从而掩盖了CORS配置错误。永远不要用Postman测试通过就认为CORS配置正确了一定要在真实浏览器环境中测试。5. 全链路问题排查与调试指南即使配置看起来正确CORS问题依然可能神出鬼没。下面是一个系统性的排查清单。5.1 浏览器网络面板深度分析打开开发者工具 - Network标签页这是排查CORS问题的第一现场。检查请求是否发出查看是否有两条相关的请求记录先OPTIONS后真实请求还是只有一条检查请求头重点关注Origin头是否被正确发送。它的值应该是当前网页的完整源如https://app.example.com。检查响应头点击出错的请求查看Response Headers。Access-Control-Allow-Origin的值是否与请求的Origin完全一致包括协议、域名、端口是否设置了Vary: Origin如果需要凭证是否有Access-Control-Allow-Credentials: true对于预检请求是否包含了Access-Control-Allow-Methods和Access-Control-Allow-Headers且包含了真实请求会用到的所有方法和头查看控制台错误信息浏览器控制台的错误信息通常非常具体例如“The ‘Access-Control-Allow-Origin‘ header has a value ‘xxx‘ that is not equal to the supplied origin.”直接指出了问题所在。5.2 服务器端日志与中间件顺序查看服务器日志确认请求是否到达了你的后端应用以及后端应用返回的响应头是什么。有时候应用服务器前的负载均衡器、WAFWeb应用防火墙或CDN可能会修改或添加CORS头导致冲突。检查中间件顺序在Node.js/Express等框架中中间件的顺序至关重要。CORS中间件必须在所有可能处理响应的路由中间件之前注册以确保每个响应都能被添加上CORS头。一个常见的错误是把CORS中间件放在了静态文件服务或具体路由之后。5.3 缓存污染问题排查这是最隐蔽的问题之一。症状是CORS配置明明改了但部分用户或浏览器仍然报旧错误。检查Vary: Origin确认服务器在所有动态设置CORS头的响应中都返回了Vary: Origin。清理客户端缓存浏览器会缓存预检请求的响应根据Access-Control-Max-Age。指导用户或开发自己强制刷新CtrlF5或清除缓存。检查CDN/代理缓存如果你使用了CDN如Cloudflare或反向代理如Nginx确保它们正确地将Origin请求头作为缓存键的一部分这依赖于Vary: Origin。你可能需要在CDN控制台进行额外的配置或执行缓存清除操作。5.4 常见错误速查表错误现象可能原因解决方案预检请求OPTIONS返回404/405服务器未处理OPTIONS方法在后端或Nginx中显式处理OPTIONS请求返回200和正确的CORS头。响应头中有多个Access-Control-Allow-Origin值多处配置冲突如Nginx和后端都设置了检查整个链路确保只有一个地方动态设置该头避免重复添加。本地开发localhost正常上线后报错生产环境白名单未配置或配置错误确保生产环境的允许源列表包含了线上前端应用的域名。携带Cookie的请求失败Access-Control-Allow-Origin为*或未设置Access-Control-Allow-Credentials: true确保动态设置为具体域名并设置Allow-Credentials: true。同时前端请求开启withCredentials。部分浏览器正常部分如Safari异常浏览器对CORS规范的实现细节有差异或缓存问题严格遵循规范设置Vary: Origin并检查Access-Control-Allow-Headers是否包含了所有必要的自定义头。我个人在多年的实践中发现CORS问题看似简单但因其涉及浏览器、服务器、网络中间件等多个环节任何一个环节的疏忽都会导致失败。最有效的调试方法就是“拉链路”从浏览器发出的原始请求开始一步步检查请求头、响应头对比CORS规范的要求像侦探一样找出不符合规范的那一个点。养成在Network面板里仔细对比Origin和Access-Control-Allow-Origin值的习惯能解决90%的CORS问题。剩下的10%多半和缓存或代理有关记住Vary: Origin是你的好朋友。 CORS多域名配置实战：从原理到Nginx与后端动态策略
1. 项目概述从单域名到多域名的CORS策略演进如果你在开发前后端分离的Web应用特别是涉及到多个子域名、多个环境开发、测试、生产或者需要为第三方提供API服务时十有八九会在浏览器的开发者工具控制台里见过这个熟悉的红色错误“Access to fetch at ‘https://api.example.com‘ from origin ‘https://app.example.com‘ has been blocked by CORS policy”。这个问题的核心就是跨源资源共享CORS策略。而解决这个问题的关键就在于服务器端正确设置Access-Control-Allow-Origin这个响应头。简单来说Access-Control-Allow-Origin就像一道门卫它告诉浏览器“我允许来自哪些‘源’Origin即协议域名端口的网页来访问我的资源。” 最省事的做法是设置一个星号*表示允许所有源访问。但这样做安全性太低相当于大门敞开任何网站都能调用你的API容易引发CSRF等安全问题。因此在生产环境中我们几乎总是需要精确指定一个或多个允许的源。当你的服务只需要允许一个固定域名访问时配置很简单直接写上那个域名就行。但现实情况往往更复杂你的前端应用可能部署在app.example.com管理后台在admin.example.com移动端H5页面在m.example.com甚至还有本地开发的localhost:3000。这时你就需要让Access-Control-Allow-Origin支持多个域名。然而这个响应头在HTTP规范中只能设置一个值你不能直接写成https://app.example.com, https://admin.example.com。如何优雅、安全且高效地解决这个“一对多”的匹配问题就是本篇文章要深入探讨的核心。2. CORS核心机制与多域名挑战解析在深入解决方案之前我们必须先理解CORS机制特别是浏览器在发起跨域请求时的完整“握手”流程。这能帮助我们明白为什么简单的静态列表行不通以及后续各种方案的底层逻辑。2.1 简单请求与预检请求CORS将请求分为两类“简单请求”和“需预检的请求”。判断标准主要看请求方法、头部和Content-Type。简单请求例如使用GET、POST、HEAD方法且Content-Type为application/x-www-form-urlencoded、multipart/form-data或text/plain。对于这类请求浏览器会直接发出并在响应中检查Access-Control-Allow-Origin头。如果匹配当前页面的源则允许访问响应数据否则抛出CORS错误。需预检的请求当请求使用了PUT、DELETE方法或Content-Type为application/json或设置了自定义头部如Authorization,X-API-Key时浏览器会先发起一个OPTIONS方法的“预检请求”。这个请求的目的是询问服务器“我打算用这些方法、这些头部从某个源发起一个真实请求你允许吗” 服务器必须在预检请求的响应中通过Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers等头部明确告知允许的范围。只有预检请求通过后浏览器才会发出真实的请求。注意很多同学在调试时发现POST请求也报CORS错误很可能就是因为Content-Type是application/json触发了预检流程但服务器没有正确处理OPTIONS请求。2.2 多域名配置的核心矛盾Access-Control-Allow-Origin响应头只能包含一个源origin或者一个星号*。这是HTTP协议的规定。这就产生了一个矛盾我们的服务需要动态地、根据请求的来源返回一个与之匹配的、单一的值。例如一个请求来自https://app.example.com我们希望响应头是Access-Control-Allow-Origin: https://app.example.com另一个请求来自https://admin.example.com我们希望响应头变成Access-Control-Allow-Origin: https://admin.example.com。服务器必须有能力在运行时动态判断请求头中的Origin值并将其与一个允许的列表进行匹配。2.3 动态匹配的必要性与Vary头由于响应头Access-Control-Allow-Origin的值会根据请求头Origin的不同而动态变化我们必须通知浏览器和中间缓存如CDN、代理服务器这个资源的响应是“可变”的它依赖于Origin请求头。这是通过设置Vary: Origin响应头来实现的。Vary: Origin告诉缓存系统“在缓存这个响应时请将Origin请求头的值作为缓存键的一部分。” 这样来自app.example.com的请求得到的响应包含Access-Control-Allow-Origin: https://app.example.com会被单独缓存不会错误地返回给来自admin.example.com的请求。忘记设置Vary: Origin是导致多域名CORS配置下缓存混乱和随机错误的常见原因。3. 主流多域名CORS配置方案实战理解了原理我们来看具体怎么实现。根据你的技术栈和部署环境有几种主流方案。3.1 方案一后端动态判断与设置最灵活通用这是最经典、控制粒度最细的方案。核心逻辑是在服务器端代码中获取请求头中的Origin值与一个预定义的白名单列表进行匹配。如果匹配成功则将该Origin值设置到Access-Control-Allow-Origin响应头中否则可以返回一个错误或者不设置该头导致浏览器CORS错误。3.1.1 Node.js (Express) 示例const express require(express); const app express(); // 允许的源白名单 const allowedOrigins [ https://app.example.com, https://admin.example.com, https://m.example.com, http://localhost:3000, http://localhost:8080 ]; // CORS中间件 app.use((req, res, next) { const origin req.headers.origin; // 检查请求来源是否在白名单中 if (allowedOrigins.includes(origin)) { res.header(Access-Control-Allow-Origin, origin); // 动态设置为请求来源 res.header(Vary, Origin); // 关键告知缓存此响应随Origin变化 res.header(Access-Control-Allow-Credentials, true); // 如果需要携带Cookie等凭证 res.header(Access-Control-Allow-Headers, Content-Type, Authorization, X-Requested-With); res.header(Access-Control-Allow-Methods, GET, POST, PUT, DELETE, OPTIONS); } // 处理预检请求 if (req.method OPTIONS) { return res.sendStatus(200); } next(); }); // 你的API路由 app.get(/api/data, (req, res) { res.json({ message: Hello CORS! }); }); app.listen(3000);实操要点白名单管理建议将allowedOrigins列表放到环境变量或配置文件中便于不同环境开发、测试、生产进行管理。Credentials处理如果前端请求需要携带Cookies或HTTP认证信息必须设置Access-Control-Allow-Credentials: true并且Access-Control-Allow-Origin不能为通配符*必须是具体的域名。同时前端在发起请求时如使用Fetch API也需要设置credentials: include。OPTIONS预检中间件中显式处理OPTIONS方法并返回200可以确保预检请求快速通过。有些CORS中间件库会帮你自动处理。3.1.2 Nginx反向代理配置如果你的后端服务不方便修改代码或者你想在基础设施层统一管理CORSNginx是一个绝佳选择。server { listen 80; server_name api.yourdomain.com; # 定义允许的源支持正则表达式 map $http_origin $cors_origin { default ; ~^https?://(app|admin|m)\.example\.com$ $http_origin; ~^http://localhost:\d$ $http_origin; } location / { # 动态设置CORS头 if ($cors_origin ! ) { add_header Access-Control-Allow-Origin $cors_origin always; add_header Vary Origin always; add_header Access-Control-Allow-Credentials true always; add_header Access-Control-Allow-Methods GET, POST, OPTIONS, PUT, DELETE always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; } # 处理预检请求 if ($request_method OPTIONS) { add_header Access-Control-Max-Age 1728000; # 缓存预检结果20天 add_header Content-Type text/plain; charsetutf-8; add_header Content-Length 0; return 204; } proxy_pass http://your_backend_server; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }注意事项add_header与always参数Nginx的add_header指令在错误响应如4xx, 5xx时默认不添加头。使用always参数确保在所有响应中都会添加CORS头这对于错误处理的统一性很重要。Access-Control-Max-Age这个头用于指定预检请求结果可以被缓存的时间秒。设置一个合理的值如7200秒/2小时可以减少不必要的预检请求提升性能。但请注意如果CORS策略变更需要等待缓存过期或客户端清理。正则表达式匹配map指令中的正则表达式提供了灵活的匹配能力可以轻松匹配一类域名如所有子域名。3.2 方案二使用成熟的中间件/库快速集成大多数现代Web框架都有成熟的CORS中间件它们封装了动态匹配、预检处理等细节。Node.js/Express:cors包 (npm install cors)const cors require(cors); const allowedOrigins [https://app.example.com, http://localhost:3000]; app.use(cors({ origin: function (origin, callback) { // 允许没有Origin头的请求如移动端App、curl if (!origin) return callback(null, true); if (allowedOrigins.indexOf(origin) -1) { return callback(new Error(CORS policy: Origin not allowed), false); } return callback(null, origin); // 动态返回匹配的origin }, credentials: true, optionsSuccessStatus: 200 // 一些老设备IE11兼容 }));Python/Flask:flask-corsfrom flask import Flask from flask_cors import CORS app Flask(__name__) CORS(app, origins[https://app.example.com, http://localhost:3000], supports_credentialsTrue)Java/Spring Boot: 在配置类中定义CorsFilter或使用CrossOrigin注解。Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); CorsConfiguration config new CorsConfiguration(); config.setAllowCredentials(true); config.addAllowedOriginPattern(*); // Spring Boot 2.4 使用模式匹配更安全 // 或者 config.setAllowedOrigins(Arrays.asList(https://app.example.com)); config.addAllowedHeader(*); config.addAllowedMethod(*); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }使用库的优缺点优点快速集成经过充分测试通常能处理边缘情况如Vary头、预检缓存。缺点可能隐藏了一些底层细节当需要高度定制化或排查复杂问题时需要深入阅读其文档和源码。3.3 方案三Origin通配符与正则匹配的陷阱与慎用你可能会想既然允许多个子域名能不能用通配符比如*.example.com答案是Access-Control-Allow-Origin头本身不支持通配符子域名。你不能设置Access-Control-Allow-Origin: *.example.com浏览器会视其为无效值。但是在一些后端框架的配置项中你可能会看到支持“通配符模式”或“正则表达式”的选项如上面Spring Boot的addAllowedOriginPattern(*)。这实际上是框架在背后帮你做了动态的字符串匹配而不是浏览器直接支持通配符。其原理等同于我们方案一中的动态判断。需要极其警惕的是使用过于宽松的通配符如*或.*会带来严重的安全风险特别是在允许携带凭证Credentials时。请始终将允许的源列表限制在最小必要范围。4. 高级场景与深度优化策略解决了基本的多域名问题后我们还会遇到一些更复杂的场景需要更精细的策略。4.1 区分环境与动态白名单在实际开发中不同环境开发、测试、预发布、生产的允许源列表是不同的。硬编码在代码里显然不可取。最佳实践环境变量配置将白名单列表配置为环境变量用分隔符如逗号、分号连接。# .env 文件 ALLOWED_ORIGINShttps://app.example.com,https://admin.example.com,http://localhost:3000然后在你的服务器代码或Nginx配置中读取并解析这个环境变量。更动态的方案数据库或配置中心对于SaaS平台或需要让客户自助添加允许域名的场景可以将白名单存储在数据库或配置中心如Consul, Apollo。在中间件中每次请求时或定时缓存从这些动态源读取并检查。此时需要注意性能务必添加缓存层。4.2 预检请求的性能优化预检请求OPTIONS会增加一次额外的网络往返对性能有影响尤其是对于高频的API调用。设置Access-Control-Max-Age如前所述这个头告诉浏览器可以将预检请求的结果缓存多久。对于稳定不变的CORS策略可以设置一个较长的时间如12小时43200。尽可能使用简单请求在设计API时如果可能考虑使用符合简单请求条件的格式如将JSON数据通过FormData发送使用application/x-www-form-urlencoded。但这通常受限于业务需求。在Nginx/CDN层缓存OPTIONS响应对于静态资源或CORS策略长期不变的API可以在Nginx或CDN配置中直接缓存对OPTIONS方法的响应进一步减轻后端压力。4.3 携带凭证Cookies、认证信息的复杂情况当请求需要携带凭证时规则更加严格服务器必须设置Access-Control-Allow-Credentials: true。服务器的Access-Control-Allow-Origin不能是通配符*必须是明确的、与请求Origin完全匹配的域名。前端发起请求时必须设置withCredentials标志Fetch API:credentials: includejQuery:xhrFields: { withCredentials: true }Axios:withCredentials: true。一个常见坑点即使你的Access-Control-Allow-Origin是动态匹配的正确域名但如果响应中包含了Access-Control-Allow-Origin: *的缓存由于未正确设置Vary: Origin浏览器也会因为*与credentials: include不兼容而拒绝请求。这再次强调了Vary: Origin的重要性。4.4 非浏览器环境与移动端AppCORS是浏览器的安全策略。对于服务器对服务器的通信如curl、Postman、后端微服务间调用或者移动端App使用WebView或网络库如OkHttp、Alamofire它们默认不强制执行CORS检查。这意味着你的API在这些环境下可能“正常工作”从而掩盖了CORS配置错误。永远不要用Postman测试通过就认为CORS配置正确了一定要在真实浏览器环境中测试。5. 全链路问题排查与调试指南即使配置看起来正确CORS问题依然可能神出鬼没。下面是一个系统性的排查清单。5.1 浏览器网络面板深度分析打开开发者工具 - Network标签页这是排查CORS问题的第一现场。检查请求是否发出查看是否有两条相关的请求记录先OPTIONS后真实请求还是只有一条检查请求头重点关注Origin头是否被正确发送。它的值应该是当前网页的完整源如https://app.example.com。检查响应头点击出错的请求查看Response Headers。Access-Control-Allow-Origin的值是否与请求的Origin完全一致包括协议、域名、端口是否设置了Vary: Origin如果需要凭证是否有Access-Control-Allow-Credentials: true对于预检请求是否包含了Access-Control-Allow-Methods和Access-Control-Allow-Headers且包含了真实请求会用到的所有方法和头查看控制台错误信息浏览器控制台的错误信息通常非常具体例如“The ‘Access-Control-Allow-Origin‘ header has a value ‘xxx‘ that is not equal to the supplied origin.”直接指出了问题所在。5.2 服务器端日志与中间件顺序查看服务器日志确认请求是否到达了你的后端应用以及后端应用返回的响应头是什么。有时候应用服务器前的负载均衡器、WAFWeb应用防火墙或CDN可能会修改或添加CORS头导致冲突。检查中间件顺序在Node.js/Express等框架中中间件的顺序至关重要。CORS中间件必须在所有可能处理响应的路由中间件之前注册以确保每个响应都能被添加上CORS头。一个常见的错误是把CORS中间件放在了静态文件服务或具体路由之后。5.3 缓存污染问题排查这是最隐蔽的问题之一。症状是CORS配置明明改了但部分用户或浏览器仍然报旧错误。检查Vary: Origin确认服务器在所有动态设置CORS头的响应中都返回了Vary: Origin。清理客户端缓存浏览器会缓存预检请求的响应根据Access-Control-Max-Age。指导用户或开发自己强制刷新CtrlF5或清除缓存。检查CDN/代理缓存如果你使用了CDN如Cloudflare或反向代理如Nginx确保它们正确地将Origin请求头作为缓存键的一部分这依赖于Vary: Origin。你可能需要在CDN控制台进行额外的配置或执行缓存清除操作。5.4 常见错误速查表错误现象可能原因解决方案预检请求OPTIONS返回404/405服务器未处理OPTIONS方法在后端或Nginx中显式处理OPTIONS请求返回200和正确的CORS头。响应头中有多个Access-Control-Allow-Origin值多处配置冲突如Nginx和后端都设置了检查整个链路确保只有一个地方动态设置该头避免重复添加。本地开发localhost正常上线后报错生产环境白名单未配置或配置错误确保生产环境的允许源列表包含了线上前端应用的域名。携带Cookie的请求失败Access-Control-Allow-Origin为*或未设置Access-Control-Allow-Credentials: true确保动态设置为具体域名并设置Allow-Credentials: true。同时前端请求开启withCredentials。部分浏览器正常部分如Safari异常浏览器对CORS规范的实现细节有差异或缓存问题严格遵循规范设置Vary: Origin并检查Access-Control-Allow-Headers是否包含了所有必要的自定义头。我个人在多年的实践中发现CORS问题看似简单但因其涉及浏览器、服务器、网络中间件等多个环节任何一个环节的疏忽都会导致失败。最有效的调试方法就是“拉链路”从浏览器发出的原始请求开始一步步检查请求头、响应头对比CORS规范的要求像侦探一样找出不符合规范的那一个点。养成在Network面板里仔细对比Origin和Access-Control-Allow-Origin值的习惯能解决90%的CORS问题。剩下的10%多半和缓存或代理有关记住Vary: Origin是你的好朋友。