前后端联调的时候你大概率见过这么一条错误Access to XMLHttpRequest at https://api.example.com/user from origin http://localhost:5173 has been blocked by CORS policy。一句话讲清什么是 CORS其实就是浏览器为了防止网页代表你去访问另一个源的数据给跨域请求加了一道“读权限”门禁服务器用响应头授权浏览器再决定要不要把响应交给你。这是前后端开发绕不开的坎不光是前端要懂后端和运维也得明白。理解了 CORS 的工作方式再看那些奇奇怪怪的报错基本就能自己判断是配置少了响应头、预检请求没处理还是 Cookie 跨域没开。这篇文章我会从同源策略说起把简单请求和预检请求、关键响应头逐个拆开再给上开发和生产环境最常用的配置最后整理一批我实际踩过的坑。1. CORS 到底在解决什么问题从同源策略说起1.1 同源策略为什么存在“同源”怎么判断浏览器有一套自己的安全模型核心之一就是同源策略。所谓同源指的是协议、域名、端口这三样完全一致。举个例子如果页面地址是https://www.example.com:443那么下面这些地址全都属于跨源http://www.example.com—— 协议不同https://api.example.com—— 域名不同https://www.example.com:8080—— 端口不同http://192.168.1.10—— 协议、域名都不同这里有一个容易忽略的细节子域名也算不同源。a.example.com和b.example.com之间默认是有安全边界的要互相访问同样需要 CORS 或者其它方案。另外很多人口语里说“跨域”严格讲其实是“跨源”CORS 的全称 Cross-Origin Resource Sharing 里用的是 Origin 而不是 Domain。虽然大家混着叫但心里要清楚浏览器判断的标准是“源”。为什么要搞同源策略因为如果没有它你登录某家网银之后再打开一个恶意网页这个恶意网页里的脚本就能带着你的登录态去请求网银接口读取你的账户信息。浏览器必须阻止这种“替用户去读另一个源的数据”的行为同源策略就是最基础的那道墙。1.2 CORS 不是禁止跨域而是给跨域请求发一张门禁授权这里要重点纠正一个常见误解跨域请求并不是发不出去。很多人以为浏览器把所有跨域请求都拦截在网关了实际上网络层请求已经正常到达服务器服务器也处理完并返回了响应。但浏览器拿到响应之后会检查响应头里有没有Access-Control-Allow-Origin这个字段。如果没有这个字段或者字段的值不匹配浏览器就把响应拦下来不让脚本读取。所以你看到的 CORS 报错本质发生在“响应返回之后”而不是“请求发出之前”。打个比方。你住在一个管理严格的小区外卖员送到大门口门卫会核对门禁名单。有登记就让外卖进来没登记就把东西拦在门外。服务器就是门卫响应头就是授权名单浏览器只认这种授权凭证。明白这一点之后会得出一个很有用的推论控制台里看到 CORS 报错不代表服务器没有收到请求服务器可能已经收到了甚至已经执行了逻辑。所以排查的时候不能只看报错就断言“请求没到后端”要先确认后端到底有没有收到这个请求这个观点在后续排查环节非常重要。2. 两种请求模式简单请求和预检请求2.1 什么情况算“简单请求”边界在哪里CORS 把请求分成两类简单请求和非简单请求。能被判定为简单请求需要同时满足几个条件关键的几个是方法只能是 GET、HEAD、POST 之一请求头只能使用浏览器自动添加的安全头以及极少数允许的自定义头不能随便添加自定义头Content-Type 只允许application/x-www-form-urlencoded、multipart/form-data、text/plain这三种。换句话说你用 axios 默认发 JSON 数据时Content-Type会是application/json已经不满足简单请求条件了。日常开发里前后端接口请求基本都会触发预检真正属于简单请求的场景反而很少。简单请求可以理解为没有自定义头、没有特殊 Content-Type、用普通表单方式发请求。浏览器认为这种请求搞不出什么大动作就直接发出去。如果服务器在响应中带上了足够的 CORS 头浏览器就把响应放行如果没带照样拦截。2.2 预检请求 OPTIONS 到底在做什么对于非简单请求浏览器会先发送一个 OPTIONS 请求这个请求叫“预检”。预检不携带实际业务数据只带两个关键请求头Access-Control-Request-Method告诉服务器后续真实请求会用什么 HTTP 方法Access-Control-Request-Headers告诉服务器后续真实请求会携带哪些自定义请求头。服务器收到预检后会返回Access-Control-Allow-Methods、Access-Control-Allow-Headers等响应头。浏览器拿到这些响应头后会核对一下服务器声明的允许范围是否覆盖真实请求的方法和自定义头。如果覆盖浏览器才继续发出真正的业务请求如果对不上浏览器直接报错真实请求根本不会发出。注意预检请求是在真实请求之前发生的所以你在 Network 面板里会看到同一个接口出现两次请求第一次是 OPTIONS第二次才是 GET 或 POST。这是非常正常的现象不是接口被调用了两次更不是后端代码有问题。这个过程可以理解成进大楼之前先到访客台报备“我要用 PUT 方法还要带 Authorization 头你们让不让进”门卫点头你才往里走门卫摇头你连闸机都到不了。很多后端新手只处理了 GET 和 POST没有单独处理 OPTIONS浏览器发预检过来时后端把它当普通请求处理甚至直接返回 404前端自然报 CORS 错。所以网关或后端必须给 OPTIONS 一个正确的响应。2.3 为什么要把请求分成两类分两类不是没事找事是为了平衡安全与性能。简单请求的风险相对低直接发可以减少一次额外网络往返非简单请求可能涉及数据修改、自定义头、认证凭证伤害面更大所以先预检确认服务器是否允许。预检的代价是一次额外请求。如果页面接口数量多且每个接口每次请求都触发预检网络开销会明显增加。减少预检有几种思路别加没必要的自定义请求头能不用application/json就不用避免触发预检用Access-Control-Max-Age让浏览器缓存预检结果避免重复预检。Access-Control-Max-Age设置得合理时对高频内网接口的性能改善非常明显。我见过一个内部管理系统接口调用很频繁加了预检缓存之后页面整体请求耗时肉眼可见地降下来了。3. 服务端配置的正确打开方式响应头逐个拆解3.1 六个核心响应头的作用与细节配置 CORS 本质上就是在配置一组响应头。下面这几个是最常用、也最容易被搞混的响应头作用注意事项Access-Control-Allow-Origin允许哪些源访问可以是*或指定源要带 Cookie 时不能直接用*Access-Control-Allow-Methods允许哪些 HTTP 方法预检时需要写全实际会用到的所有方法Access-Control-Allow-Headers允许哪些请求头预检时需要要和前端实际带的自定义头一致Access-Control-Allow-Credentials是否允许携带凭证true表示允许 Cookie、HTTP 认证等凭证Access-Control-Expose-Headers允许脚本读取哪些响应头默认只能读几个基础响应头自定义响应头要在这里声明Access-Control-Max-Age预检结果缓存时间单位秒太长会导致服务端配置变更后生效变慢我这里最想说的一坑是*和Access-Control-Allow-Credentials不能同时出现。一旦服务器返回Access-Control-Allow-Origin: *同时又返回Access-Control-Allow-Credentials: true浏览器会直接拒绝报错信息里会明确写“must not be the wildcard * when credentials mode is include”。原因是*等于对全世界开放再允许带凭证就太危险了。如果业务确实需要跨域带 Cookie就必须写具体的 Origin或者动态返回请求方 Origin 并做白名单校验。另一个容易漏掉的是Access-Control-Expose-Headers。前端如果希望通过response.headers读取后端返回的X-Request-Id或X-Rate-Limit-Remaining这类自定义响应头光后端设置了这个头还不够还要在Expose-Headers里声明出来否则脚本是读不到的。这个点很容易被忽略因为后端明明返回了前端却总是拿到undefined查起来特别迷惑。3.2 三段参考配置Node、Nginx、Spring Boot先看 Node.js 里最常见的中间件写法app.use((req, res, next) { // 生产环境建议从白名单判断动态返回 Origin res.setHeader(Access-Control-Allow-Origin, https://app.example.com); res.setHeader(Access-Control-Allow-Methods, GET, POST, PUT, DELETE, OPTIONS); res.setHeader(Access-Control-Allow-Headers, Content-Type, Authorization); res.setHeader(Access-Control-Allow-Credentials, true); // 直接短路预检请求 if (req.method OPTIONS) { res.sendStatus(204); return; } next(); });这里把 OPTIONS 单独拦截直接返回 204 特别重要。如果不短路预检请求会继续往下走到业务路由可能被鉴权逻辑拦截返回 401 或 403前端同样会报 CORS 错误。再看 Nginx 作为反向代理时的配置location /api/ { add_header Access-Control-Allow-Origin $http_origin; 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 86400; if ($request_method OPTIONS) { return 204; } proxy_pass http://backend-server; }这里用$http_origin动态回写请求方源适用于需要多个前端域名的场景。但要记得在同一个 server 或 location 里配合白名单逻辑不能无条件信任任何 Origin。Spring Boot 项目里我更推荐使用全局配置类而不是在 Controller 上一个个加注解Configuration public class CorsConfig { Bean public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurer() { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(https://app.example.com) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }; } }这样所有/api/**路径的接口都会统一应用 CORS 配置不用每个接口单独处理减少遗漏。3.3 多个允许源怎么处理动态 Origin 与安全边界生产环境经常遇到这类问题系统有多个前端域名但Access-Control-Allow-Origin只能填一个值或者*不能填多个。这是高频误区。要让多个来源都能访问常见做法是读取请求头里的 Origin做白名单校验匹配成功之后把 Origin 原样写回响应头。同时一定要返回Vary: Origin让浏览器和缓存代理知道这个响应的内容取决于 Origin 请求头避免某个前端域名的响应被缓存后误发给另一个域名。安全方面尤其要注意如果代码只是简单地把请求里的 Origin 无条件返回等于任何来源都能读接口数据这就失去了跨域限制的意义。正确做法是维护一个允许源列表只有命中列表的 Origin 才被回写。可以理解成门卫要看你的登记记录而不是你说自己是谁就是谁。4. 开发环境与生产环境的落地实战4.1 本地开发最省事的方案用代理转发而不是和 CORS 硬刚现在很多前端项目都有开发服务器开发时跨域最常用的是代理配置。比如 Vite 里的server.proxy// vite.config.js export default { server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }Webpack 也有类似的devServer.proxy配置。它的原理其实特别简单浏览器向同源的前端开发服务器发请求开发服务器在服务端把请求转发到后端服务服务端之间没有浏览器同源策略的限制响应再原样回给浏览器。对浏览器来说它始终只访问了localhost:5173同源自然成立。这个方案的优点是开发阶段可以把跨域问题先放一放前端专注写业务逻辑POST、自定义头、Cookie 这些都可以正常工作。但要清醒地认识到代理解决的是“浏览器访问路径”的同源问题并不等于后端真的配置好了 CORS。上线之后如果前后端部署在不同域名下还是需要后端配合 CORS 或统一网关来处理。所以把代理当成开发提效工具不要当成 CORS 的替代品。4.2 用网关统一处理 CORS业务服务不背锅在微服务或前后端分离架构里我更推荐把 CORS 处理放在网关层而不是让每个业务服务自己配置。好处很明显前端只和网关这一个地址打交道加白名单只改一处各业务服务完全不用关心 OPTIONS 预检请求安全策略收敛在同一个位置后续审计和维护都方便很多。网关处理 CORS 时要注意几个关键点确认路由匹配范围CORS 配置要覆盖前端实际会访问的路径公共响应头统一设置避免每个路由重复配置对 OPTIONS 请求做短路处理统一返回 204不要让预检落到业务服务动态 Origin 白名单、Vary: Origin这些细节也要一并处理。正常情况下预检请求不包含业务逻辑直接短路返回即可。如果让预检请求一路透传到后端很可能被业务代码里的过滤器、鉴权逻辑拦下来结果前端看到的还是 CORS 报错。4.3 跨域携带 Cookie 的完整链路前端用 axios 时有个withCredentials开关设为true之后浏览器才会在跨域请求里带上 Cookie。对应地后端必须返回Access-Control-Allow-Credentials: true同时Access-Control-Allow-Origin不能是*。这三个条件缺一个Cookie 就带不过去。不过还有一个非常隐蔽的坑Cookie 本身的SameSite属性。浏览器对SameSite有默认策略如果服务端下发 Cookie 时是SameSiteLax那么跨站请求时 Cookie 可能不会被携带。平时开发时遇到跨域 Cookie 丢失先别急着怀疑 CORS 配置去看一眼浏览器 Application 面板里 Cookie 的 SameSite 值。如果确实需要跨站携带通常要把 Cookie 设置为SameSiteNone并配合Secure标志但这也意味着必须是 HTTPS 环境。这个点我印象很深。有段时间某个项目跨域登录一直失败后端一口咬定 CORS 配置没问题前端也确认withCredentials开了最后查下来是 Cookie 的 SameSite 属性导致的。所以跨域带凭证这个问题得从前端配置、后端 CORS、Cookie 属性三方面同时排查少一环都找不到原因。5. 常见报错与排查技巧实录5.1 三条高频报错逐字拆解CORS 报错信息虽然五花八门但绝大多数可以归到下面这几类报错特征发生阶段常规原因排查方向No Access-Control-Allow-Origin header is present真实请求响应后后端响应里没有这个响应头检查响应头是否缺失、配置是否生效Response to preflight request doesnt pass access control check预检阶段OPTIONS 未正确处理或允许方法/头不覆盖单独看 OPTIONS 的响应和 Allow 字段must not be the wildcard * when credentials mode is include真实请求响应后*与 Allow-Credentials 同时出现改成具体 Origin 白名单或去掉凭证Request header field xxx is not allowed by Access-Control-Allow-Headers预检阶段前端带了服务端未允许的自定义头在 Allow-Headers 里补充对应名称第一种报错最常见本质是后端响应里压根没有Access-Control-Allow-Origin这个头。排查时先打开 Network 面板看真实接口的响应头里有没有这个字段。没有的话检查后端配置是否生效、是不是网关把响应头过滤掉了、Nginx 的 add_header 是不是写错了位置。第二种报错说明预检没有通过。多半是后端没有单独处理 OPTIONS 请求或者返回的Allow-Methods、Allow-Headers没有覆盖前端实际使用的方法和请求头。可以先看那个 OPTIONS 请求的状态码如果是 404、401、405基本就是后端没有正确放行预检。5.2 一套实用的排查流程我踩过很多次坑之后总结出一个固定流程遇到 CORS 报错就按这个顺序来打开浏览器 Network 面板确认那条跨域请求有没有出现在请求列表里有的话点进去看请求头、响应头看是不是先发了一个 OPTIONS 预检预检的状态码和响应头是否正常用 curl 直接请求接口带上Origin请求头看后端实际返回的响应头如果 curl 能拿到正确的响应头而浏览器依然报错就把重点放到 Cookie、SameSite、浏览器扩展这类因素上。curl 示例curl -i -H Origin: http://localhost:5173 https://api.example.com/user重点看响应头里的Access-Control-Allow-Origin等内容。curl 没有浏览器同源策略所以它能直接看到服务端真正返回了什么是排除浏览器干扰的利器。很多场景里curl 一看就知道服务端压根没配置 CORS那就不用再折腾前端了。5.3 几个容易让人卡住半天的特殊场景最后记录几个我亲自遇到过的特殊坑每一个都很有迷惑性。第一个是 Origin 被写死的问题。某次本地开发一直报 CORS后端查了半天最后发现网关里Access-Control-Allow-Origin被写死成了生产域名。本地调试环境没有命中白名单自然被拦截但部署到生产环境之后这个报错又会离奇消失。解决办法是让 Origin 白名单从环境变量读取不同环境动态配置。第二个是自定义请求头引发的连锁问题。前端以为加一个X-Client-Version没什么问题但这个头不是浏览器默认允许的直接触发预检。如果服务端Allow-Headers里没有它预检就不过。这类问题排查时只要多看一眼 Network 面板里有没有多出来的 OPTIONS 请求就能快速定位。第三个是本地调试地址不一致。localhost和127.0.0.1对浏览器来说是两个完全不同的源接口请求从http://localhost:5173发到http://127.0.0.1:8080同样会被 CORS 拦截。这种问题特别容易让人忽略因为心理上觉得“这不就是本机嘛”。第四个是多个响应头值的问题。有的框架或者配置会在响应头里拼出多个 Origin 值比如Access-Control-Allow-Origin: https://a.example.com, https://b.example.com这是不合法的。浏览器要求这个头要么是*要么是单个具体源。处理多个来源还是要用动态 Origin 加白名单的方式。最后再分享一个小技巧排查 CORS 问题时记住“看头、看预检、看凭证”这九个字。先看响应头缺什么再看有没有提前冒出 OPTIONS 请求最后看是否涉及 Cookie 和 SameSite。把这三步走完绝大多数跨域问题都能定位到具体环节。我自己现在遇到 CORS 报错第一反应已经不再是急着加一个*而是先判断这次请求属于简单请求还是预检请求响应头里到底少了哪一环。搞清楚 CORS 是“服务端授权、浏览器执行”的机制之后那些看似莫名其妙的报错其实每一步都有迹可循。
前后端联调的时候你大概率见过这么一条错误Access to XMLHttpRequest at https://api.example.com/user from origin http://localhost:5173 has been blocked by CORS policy。一句话讲清什么是 CORS其实就是浏览器为了防止网页代表你去访问另一个源的数据给跨域请求加了一道“读权限”门禁服务器用响应头授权浏览器再决定要不要把响应交给你。这是前后端开发绕不开的坎不光是前端要懂后端和运维也得明白。理解了 CORS 的工作方式再看那些奇奇怪怪的报错基本就能自己判断是配置少了响应头、预检请求没处理还是 Cookie 跨域没开。这篇文章我会从同源策略说起把简单请求和预检请求、关键响应头逐个拆开再给上开发和生产环境最常用的配置最后整理一批我实际踩过的坑。1. CORS 到底在解决什么问题从同源策略说起1.1 同源策略为什么存在“同源”怎么判断浏览器有一套自己的安全模型核心之一就是同源策略。所谓同源指的是协议、域名、端口这三样完全一致。举个例子如果页面地址是https://www.example.com:443那么下面这些地址全都属于跨源http://www.example.com—— 协议不同https://api.example.com—— 域名不同https://www.example.com:8080—— 端口不同http://192.168.1.10—— 协议、域名都不同这里有一个容易忽略的细节子域名也算不同源。a.example.com和b.example.com之间默认是有安全边界的要互相访问同样需要 CORS 或者其它方案。另外很多人口语里说“跨域”严格讲其实是“跨源”CORS 的全称 Cross-Origin Resource Sharing 里用的是 Origin 而不是 Domain。虽然大家混着叫但心里要清楚浏览器判断的标准是“源”。为什么要搞同源策略因为如果没有它你登录某家网银之后再打开一个恶意网页这个恶意网页里的脚本就能带着你的登录态去请求网银接口读取你的账户信息。浏览器必须阻止这种“替用户去读另一个源的数据”的行为同源策略就是最基础的那道墙。1.2 CORS 不是禁止跨域而是给跨域请求发一张门禁授权这里要重点纠正一个常见误解跨域请求并不是发不出去。很多人以为浏览器把所有跨域请求都拦截在网关了实际上网络层请求已经正常到达服务器服务器也处理完并返回了响应。但浏览器拿到响应之后会检查响应头里有没有Access-Control-Allow-Origin这个字段。如果没有这个字段或者字段的值不匹配浏览器就把响应拦下来不让脚本读取。所以你看到的 CORS 报错本质发生在“响应返回之后”而不是“请求发出之前”。打个比方。你住在一个管理严格的小区外卖员送到大门口门卫会核对门禁名单。有登记就让外卖进来没登记就把东西拦在门外。服务器就是门卫响应头就是授权名单浏览器只认这种授权凭证。明白这一点之后会得出一个很有用的推论控制台里看到 CORS 报错不代表服务器没有收到请求服务器可能已经收到了甚至已经执行了逻辑。所以排查的时候不能只看报错就断言“请求没到后端”要先确认后端到底有没有收到这个请求这个观点在后续排查环节非常重要。2. 两种请求模式简单请求和预检请求2.1 什么情况算“简单请求”边界在哪里CORS 把请求分成两类简单请求和非简单请求。能被判定为简单请求需要同时满足几个条件关键的几个是方法只能是 GET、HEAD、POST 之一请求头只能使用浏览器自动添加的安全头以及极少数允许的自定义头不能随便添加自定义头Content-Type 只允许application/x-www-form-urlencoded、multipart/form-data、text/plain这三种。换句话说你用 axios 默认发 JSON 数据时Content-Type会是application/json已经不满足简单请求条件了。日常开发里前后端接口请求基本都会触发预检真正属于简单请求的场景反而很少。简单请求可以理解为没有自定义头、没有特殊 Content-Type、用普通表单方式发请求。浏览器认为这种请求搞不出什么大动作就直接发出去。如果服务器在响应中带上了足够的 CORS 头浏览器就把响应放行如果没带照样拦截。2.2 预检请求 OPTIONS 到底在做什么对于非简单请求浏览器会先发送一个 OPTIONS 请求这个请求叫“预检”。预检不携带实际业务数据只带两个关键请求头Access-Control-Request-Method告诉服务器后续真实请求会用什么 HTTP 方法Access-Control-Request-Headers告诉服务器后续真实请求会携带哪些自定义请求头。服务器收到预检后会返回Access-Control-Allow-Methods、Access-Control-Allow-Headers等响应头。浏览器拿到这些响应头后会核对一下服务器声明的允许范围是否覆盖真实请求的方法和自定义头。如果覆盖浏览器才继续发出真正的业务请求如果对不上浏览器直接报错真实请求根本不会发出。注意预检请求是在真实请求之前发生的所以你在 Network 面板里会看到同一个接口出现两次请求第一次是 OPTIONS第二次才是 GET 或 POST。这是非常正常的现象不是接口被调用了两次更不是后端代码有问题。这个过程可以理解成进大楼之前先到访客台报备“我要用 PUT 方法还要带 Authorization 头你们让不让进”门卫点头你才往里走门卫摇头你连闸机都到不了。很多后端新手只处理了 GET 和 POST没有单独处理 OPTIONS浏览器发预检过来时后端把它当普通请求处理甚至直接返回 404前端自然报 CORS 错。所以网关或后端必须给 OPTIONS 一个正确的响应。2.3 为什么要把请求分成两类分两类不是没事找事是为了平衡安全与性能。简单请求的风险相对低直接发可以减少一次额外网络往返非简单请求可能涉及数据修改、自定义头、认证凭证伤害面更大所以先预检确认服务器是否允许。预检的代价是一次额外请求。如果页面接口数量多且每个接口每次请求都触发预检网络开销会明显增加。减少预检有几种思路别加没必要的自定义请求头能不用application/json就不用避免触发预检用Access-Control-Max-Age让浏览器缓存预检结果避免重复预检。Access-Control-Max-Age设置得合理时对高频内网接口的性能改善非常明显。我见过一个内部管理系统接口调用很频繁加了预检缓存之后页面整体请求耗时肉眼可见地降下来了。3. 服务端配置的正确打开方式响应头逐个拆解3.1 六个核心响应头的作用与细节配置 CORS 本质上就是在配置一组响应头。下面这几个是最常用、也最容易被搞混的响应头作用注意事项Access-Control-Allow-Origin允许哪些源访问可以是*或指定源要带 Cookie 时不能直接用*Access-Control-Allow-Methods允许哪些 HTTP 方法预检时需要写全实际会用到的所有方法Access-Control-Allow-Headers允许哪些请求头预检时需要要和前端实际带的自定义头一致Access-Control-Allow-Credentials是否允许携带凭证true表示允许 Cookie、HTTP 认证等凭证Access-Control-Expose-Headers允许脚本读取哪些响应头默认只能读几个基础响应头自定义响应头要在这里声明Access-Control-Max-Age预检结果缓存时间单位秒太长会导致服务端配置变更后生效变慢我这里最想说的一坑是*和Access-Control-Allow-Credentials不能同时出现。一旦服务器返回Access-Control-Allow-Origin: *同时又返回Access-Control-Allow-Credentials: true浏览器会直接拒绝报错信息里会明确写“must not be the wildcard * when credentials mode is include”。原因是*等于对全世界开放再允许带凭证就太危险了。如果业务确实需要跨域带 Cookie就必须写具体的 Origin或者动态返回请求方 Origin 并做白名单校验。另一个容易漏掉的是Access-Control-Expose-Headers。前端如果希望通过response.headers读取后端返回的X-Request-Id或X-Rate-Limit-Remaining这类自定义响应头光后端设置了这个头还不够还要在Expose-Headers里声明出来否则脚本是读不到的。这个点很容易被忽略因为后端明明返回了前端却总是拿到undefined查起来特别迷惑。3.2 三段参考配置Node、Nginx、Spring Boot先看 Node.js 里最常见的中间件写法app.use((req, res, next) { // 生产环境建议从白名单判断动态返回 Origin res.setHeader(Access-Control-Allow-Origin, https://app.example.com); res.setHeader(Access-Control-Allow-Methods, GET, POST, PUT, DELETE, OPTIONS); res.setHeader(Access-Control-Allow-Headers, Content-Type, Authorization); res.setHeader(Access-Control-Allow-Credentials, true); // 直接短路预检请求 if (req.method OPTIONS) { res.sendStatus(204); return; } next(); });这里把 OPTIONS 单独拦截直接返回 204 特别重要。如果不短路预检请求会继续往下走到业务路由可能被鉴权逻辑拦截返回 401 或 403前端同样会报 CORS 错误。再看 Nginx 作为反向代理时的配置location /api/ { add_header Access-Control-Allow-Origin $http_origin; 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 86400; if ($request_method OPTIONS) { return 204; } proxy_pass http://backend-server; }这里用$http_origin动态回写请求方源适用于需要多个前端域名的场景。但要记得在同一个 server 或 location 里配合白名单逻辑不能无条件信任任何 Origin。Spring Boot 项目里我更推荐使用全局配置类而不是在 Controller 上一个个加注解Configuration public class CorsConfig { Bean public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurer() { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(https://app.example.com) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }; } }这样所有/api/**路径的接口都会统一应用 CORS 配置不用每个接口单独处理减少遗漏。3.3 多个允许源怎么处理动态 Origin 与安全边界生产环境经常遇到这类问题系统有多个前端域名但Access-Control-Allow-Origin只能填一个值或者*不能填多个。这是高频误区。要让多个来源都能访问常见做法是读取请求头里的 Origin做白名单校验匹配成功之后把 Origin 原样写回响应头。同时一定要返回Vary: Origin让浏览器和缓存代理知道这个响应的内容取决于 Origin 请求头避免某个前端域名的响应被缓存后误发给另一个域名。安全方面尤其要注意如果代码只是简单地把请求里的 Origin 无条件返回等于任何来源都能读接口数据这就失去了跨域限制的意义。正确做法是维护一个允许源列表只有命中列表的 Origin 才被回写。可以理解成门卫要看你的登记记录而不是你说自己是谁就是谁。4. 开发环境与生产环境的落地实战4.1 本地开发最省事的方案用代理转发而不是和 CORS 硬刚现在很多前端项目都有开发服务器开发时跨域最常用的是代理配置。比如 Vite 里的server.proxy// vite.config.js export default { server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }Webpack 也有类似的devServer.proxy配置。它的原理其实特别简单浏览器向同源的前端开发服务器发请求开发服务器在服务端把请求转发到后端服务服务端之间没有浏览器同源策略的限制响应再原样回给浏览器。对浏览器来说它始终只访问了localhost:5173同源自然成立。这个方案的优点是开发阶段可以把跨域问题先放一放前端专注写业务逻辑POST、自定义头、Cookie 这些都可以正常工作。但要清醒地认识到代理解决的是“浏览器访问路径”的同源问题并不等于后端真的配置好了 CORS。上线之后如果前后端部署在不同域名下还是需要后端配合 CORS 或统一网关来处理。所以把代理当成开发提效工具不要当成 CORS 的替代品。4.2 用网关统一处理 CORS业务服务不背锅在微服务或前后端分离架构里我更推荐把 CORS 处理放在网关层而不是让每个业务服务自己配置。好处很明显前端只和网关这一个地址打交道加白名单只改一处各业务服务完全不用关心 OPTIONS 预检请求安全策略收敛在同一个位置后续审计和维护都方便很多。网关处理 CORS 时要注意几个关键点确认路由匹配范围CORS 配置要覆盖前端实际会访问的路径公共响应头统一设置避免每个路由重复配置对 OPTIONS 请求做短路处理统一返回 204不要让预检落到业务服务动态 Origin 白名单、Vary: Origin这些细节也要一并处理。正常情况下预检请求不包含业务逻辑直接短路返回即可。如果让预检请求一路透传到后端很可能被业务代码里的过滤器、鉴权逻辑拦下来结果前端看到的还是 CORS 报错。4.3 跨域携带 Cookie 的完整链路前端用 axios 时有个withCredentials开关设为true之后浏览器才会在跨域请求里带上 Cookie。对应地后端必须返回Access-Control-Allow-Credentials: true同时Access-Control-Allow-Origin不能是*。这三个条件缺一个Cookie 就带不过去。不过还有一个非常隐蔽的坑Cookie 本身的SameSite属性。浏览器对SameSite有默认策略如果服务端下发 Cookie 时是SameSiteLax那么跨站请求时 Cookie 可能不会被携带。平时开发时遇到跨域 Cookie 丢失先别急着怀疑 CORS 配置去看一眼浏览器 Application 面板里 Cookie 的 SameSite 值。如果确实需要跨站携带通常要把 Cookie 设置为SameSiteNone并配合Secure标志但这也意味着必须是 HTTPS 环境。这个点我印象很深。有段时间某个项目跨域登录一直失败后端一口咬定 CORS 配置没问题前端也确认withCredentials开了最后查下来是 Cookie 的 SameSite 属性导致的。所以跨域带凭证这个问题得从前端配置、后端 CORS、Cookie 属性三方面同时排查少一环都找不到原因。5. 常见报错与排查技巧实录5.1 三条高频报错逐字拆解CORS 报错信息虽然五花八门但绝大多数可以归到下面这几类报错特征发生阶段常规原因排查方向No Access-Control-Allow-Origin header is present真实请求响应后后端响应里没有这个响应头检查响应头是否缺失、配置是否生效Response to preflight request doesnt pass access control check预检阶段OPTIONS 未正确处理或允许方法/头不覆盖单独看 OPTIONS 的响应和 Allow 字段must not be the wildcard * when credentials mode is include真实请求响应后*与 Allow-Credentials 同时出现改成具体 Origin 白名单或去掉凭证Request header field xxx is not allowed by Access-Control-Allow-Headers预检阶段前端带了服务端未允许的自定义头在 Allow-Headers 里补充对应名称第一种报错最常见本质是后端响应里压根没有Access-Control-Allow-Origin这个头。排查时先打开 Network 面板看真实接口的响应头里有没有这个字段。没有的话检查后端配置是否生效、是不是网关把响应头过滤掉了、Nginx 的 add_header 是不是写错了位置。第二种报错说明预检没有通过。多半是后端没有单独处理 OPTIONS 请求或者返回的Allow-Methods、Allow-Headers没有覆盖前端实际使用的方法和请求头。可以先看那个 OPTIONS 请求的状态码如果是 404、401、405基本就是后端没有正确放行预检。5.2 一套实用的排查流程我踩过很多次坑之后总结出一个固定流程遇到 CORS 报错就按这个顺序来打开浏览器 Network 面板确认那条跨域请求有没有出现在请求列表里有的话点进去看请求头、响应头看是不是先发了一个 OPTIONS 预检预检的状态码和响应头是否正常用 curl 直接请求接口带上Origin请求头看后端实际返回的响应头如果 curl 能拿到正确的响应头而浏览器依然报错就把重点放到 Cookie、SameSite、浏览器扩展这类因素上。curl 示例curl -i -H Origin: http://localhost:5173 https://api.example.com/user重点看响应头里的Access-Control-Allow-Origin等内容。curl 没有浏览器同源策略所以它能直接看到服务端真正返回了什么是排除浏览器干扰的利器。很多场景里curl 一看就知道服务端压根没配置 CORS那就不用再折腾前端了。5.3 几个容易让人卡住半天的特殊场景最后记录几个我亲自遇到过的特殊坑每一个都很有迷惑性。第一个是 Origin 被写死的问题。某次本地开发一直报 CORS后端查了半天最后发现网关里Access-Control-Allow-Origin被写死成了生产域名。本地调试环境没有命中白名单自然被拦截但部署到生产环境之后这个报错又会离奇消失。解决办法是让 Origin 白名单从环境变量读取不同环境动态配置。第二个是自定义请求头引发的连锁问题。前端以为加一个X-Client-Version没什么问题但这个头不是浏览器默认允许的直接触发预检。如果服务端Allow-Headers里没有它预检就不过。这类问题排查时只要多看一眼 Network 面板里有没有多出来的 OPTIONS 请求就能快速定位。第三个是本地调试地址不一致。localhost和127.0.0.1对浏览器来说是两个完全不同的源接口请求从http://localhost:5173发到http://127.0.0.1:8080同样会被 CORS 拦截。这种问题特别容易让人忽略因为心理上觉得“这不就是本机嘛”。第四个是多个响应头值的问题。有的框架或者配置会在响应头里拼出多个 Origin 值比如Access-Control-Allow-Origin: https://a.example.com, https://b.example.com这是不合法的。浏览器要求这个头要么是*要么是单个具体源。处理多个来源还是要用动态 Origin 加白名单的方式。最后再分享一个小技巧排查 CORS 问题时记住“看头、看预检、看凭证”这九个字。先看响应头缺什么再看有没有提前冒出 OPTIONS 请求最后看是否涉及 Cookie 和 SameSite。把这三步走完绝大多数跨域问题都能定位到具体环节。我自己现在遇到 CORS 报错第一反应已经不再是急着加一个*而是先判断这次请求属于简单请求还是预检请求响应头里到底少了哪一环。搞清楚 CORS 是“服务端授权、浏览器执行”的机制之后那些看似莫名其妙的报错其实每一步都有迹可循。
