跨域Cookie写入失败？CORS与SameSite配置全攻略

搞前后端分离最头疼的接口联调阶段十次里有八次都栽在跨域上。尤其当你辛辛苦苦把登录接口调通结果发现浏览器控制台报了个“has been blocked by cors policy”的错误而这次不是因为没配CORS是因为你配了CORS但Cookie死活写不进浏览器。这个问题很典型几乎所有做账号体系、单点登录、用户态保持的同学都会撞上。这篇文章就从CORS和Cookie的配合机制讲起把“跨域写Cookie”这条链路彻底拆开覆盖原理、配置、踩坑和排查方法适合正在做前后端分离项目、或者第一次碰跨域登录方案的开发者当作手边参考。CORS本身不复杂复杂的是它跟Cookie组合在一起时浏览器的约束会从“一套”变成“两套”——一套管请求能不能发出去一套管Cookie能不能写进去。很多人只配了第一套第二套压根没想到结果就是请求通了、Cookie没影儿登录态一刷新就丢。1. 为什么跨域请求默认不带Cookie先搞清楚同源与跨域1.1 同源的定义与浏览器默认策略要理解CORS和Cookie的关系第一件事是搞清楚什么叫“同源”。浏览器判断一个请求是不是跨域看的是三个东西协议、域名、端口。三者完全一致才算同源任何一个不同都算跨域。比如前端部署在http://localhost:8080后端接口跑在http://localhost:9090端口不同跨域没得商量。协议也不同也一样哪怕域名端口一样只要一个http一个https照样跨域。浏览器之所以搞同源策略本质上是安全隔离页面里的脚本不能随便读取另一个源的资源不然你在A网站打开的页面就能偷偷请求B网站的数据那整个互联网的账号体系都崩了。这个策略从Netscape时代就有了到目前为止依然是Web安全的地基。同源策略有两种表现一种是“发不出去”比如XHR和fetch发跨域请求时浏览器会拦截响应另一种是“收不回来”比如img、script标签可以发跨域请求但页面脚本读不到响应内容。CORSCross-Origin Resource Sharing跨域资源共享就是用来解决“发不出去”这一类问题的标准方案它由服务器在响应头里告诉浏览器“这个源是我信任的你可以把响应交给页面脚本。”没有这个头浏览器就会直接拦控制台就是你熟悉的那句“has been blocked by cors policy”。注意一个细节跨域请求本身可能已经到了服务器服务器也处理完并返回了数据但浏览器在把响应交给JS之前发现CORS头不合规于是把响应扣了下来。所以很多后端同学会疑惑“我接口明明返回了为什么前端说没数据”——没数据是因为响应被浏览器拦了不是没响应。1.2 跨域请求中Cookie被“扣留”的真相现在关键问题来了跨域请求默认情况下浏览器不会携带目标域名的Cookie也不会接受服务器在跨域响应里发过来的Set-Cookie指令。很多同学第一次遇到跨域登录问题时发现后端明明返回了Set-Cookie: session_idabc123但打开Application面板一看Cookie列表空空如也就是这个原因。浏览器这么做的逻辑不复杂Cookie是浏览器按域名维度存储的凭证信息如果任何一个跨域响应都能随手往你的浏览器里塞Cookie那恶意网站就能通过请求你的接口强行种下钓鱼Cookie或者诱导你的浏览器带着某个域的Cookie发起危险操作。所以浏览器在跨域场景下对Cookie做了“双重保险”默认不带、默认不收。要在跨域场景下带Cookie、收Cookie必须同时满足三个条件服务器显式允许携带凭证Access-Control-Allow-Credentials: true、Access-Control-Allow-Origin不能是通配符*、前端请求设置了withCredentials或credentials: include。三个条件缺一个Cookie就过不来。这个组合拳就是本文的核心后面我会逐一展开。1.3 简单请求与预检请求聊CORS绕不开预检请求Preflight。浏览器把跨域请求分成两类简单请求和预检请求。简单请求是指请求方法是GET、POST、HEAD且Content-Type只允许application/x-www-form-urlencoded、multipart/form-data、text/plain同时没有自定义请求头的请求。这类请求浏览器直接发不预检。其他情况比如请求头带了Authorization、Content-Type: application/json或者请求方法是PUT、DELETE等浏览器都会先发一个OPTIONS请求去试探服务端允许哪些跨域操作服务端返回对应的CORS头之后浏览器才会发真正的业务请求。这个机制跟Cookie有组合关系因为当你设置了credentials: include之后预检请求是发不出去Cookie的预检本质上是一个没有凭证的“试探”。还有一点预检请求绝大多数情况下不携带Cookie但响应头里的Access-Control-Allow-Credentials必须在预检响应里也出现否则浏览器会认为整个跨域凭证策略不成立。很多人在正式接口上把CORS头配全了却漏了OPTIONS的响应导致预检阶段就直接被拦压根走不到正式请求。2. 打开跨域Cookie通道的关键CORS的四个核心响应头2.1 Access-Control-Allow-Origin不能再用通配符CORS配置里大家最熟悉的就是Access-Control-Allow-Origin这个头控制允许哪些源访问资源。平时做联调图省事很多人直接写Access-Control-Allow-Origin: *这样所有源都能访问开发时很爽。但只要涉及Cookie这个*就是行不通的。原因在浏览器规范里写死了当Access-Control-Allow-Credentials: true时Access-Control-Allow-Origin不能是*必须是具体的源。浏览器看到*和Credentials: true同时出现会直接判定请求不合法在控制台报“The value of the Access-Control-Allow-Origin header in the response must not be the wildcard * when the requests credentials mode is include”。所以正确的做法是把允许的源写死比如你的前端部署在http://localhost:8080那就返回Access-Control-Allow-Origin: http://localhost:8080。如果前端域名可能变化比如有多个测试环境服务端可以动态取请求的Origin头来做白名单校验校验通过就回显这个源校验不通过就不返回CORS头——这就是热词里提到的“反射Origin”。配置反射Origin本身没问题问题在于不能无脑反射如果不对Origin做白名单校验就直接原样返回相当于任何人都能从任意源跨域调用你的接口配合Credentials: true等于把-Sensitive接口的Cookie凭证暴露给了任意恶意站点这就是热词里说的“反射Origin credentialstrue导致的CORS配置错误”的核心风险。2.2 Access-Control-Allow-Credentials允许携带凭证的开关Access-Control-Allow-Credentials是跨域Cookie的“总闸门”。这个头只有两个值true布尔值注意不是字符串true响应头里写true即可或者不设置。设置成true表示服务器明确允许跨域请求携带凭证Credentials这里的凭证主要指Cookie也包括TLS客户端证书等。你不设置这个头前端就算把withCredentials设成true也没用浏览器依然不会带Cookie。需要提醒的是这个头一旦打开整个CORS域就进入了“精确匹配模式”。除了Origin不能为*之外Access-Control-Allow-Headers和Access-Control-Allow-Methods也建议明确指定不要用*含糊带过。原因不是浏览器强制要求实际上Headers和Methods在Credentials模式下是允许用*的而是从安全审计的角度明确白名单比通配符好排查一旦出问题你能快速理清是谁在什么时候用什么方式访问了接口。2.3 Access-Control-Allow-Headers与Allow-Methods预检放行前面提到非简单请求需要预检预检通过的标准之一就是服务端返回的Access-Control-Allow-Headers包含请求头里的所有自定义字段Access-Control-Allow-Methods包含请求使用的方法。如果你在请求头里带了Authorization或者Content-Type: application/json但服务端预检响应里没有列出这些头浏览器会在预检阶段直接报错错误提示通常是“Request header field authorization is not allowed by Access-Control-Allow-Headers in preflight response”。在Cookie场景下这一个点常被忽略。有同学配置了Origin和Credentials结果前端带Cookie的请求依然发不出去翻看控制台才发现卡在预检上。其实预检错误和Cookie没有直接关系但因为登录接口几乎都是application/json且请求头常带X-Requested-With这类自定义字段所以一定会触发预检。等于说你前面把Origin和Credentials配好了预检这关没过一切白搭。2.4 反射Origin与固定Origin的取舍这一节展开说下Origin配置的具体方案。我见过三种常见做法第一种写死一个源。Access-Control-Allow-Origin: http://localhost:8080。优点是最简单、最安全缺点是每换一个前端域名就要改一次后端配置多环境联调时很烦。第二种动态反射Origin但做白名单校验。也就是写一个过滤器读取请求的Origin头查一下是否在预先配置好的允许列表里如果在就把该Origin原样返回如果不在不返回任何CORS头浏览器拦截。这个方案兼顾了灵活性和安全性是目前生产环境最常见的做法。但网上很多教程直接把“反射Origin”教成了“谁请求就反射谁”完全没有白名单这就危险了。第三种用Nginx/网关层统一处理CORS。后端服务不再管CORS统一在网关层按域名规则配置。这个方案适合微服务架构因为CORS配置收敛在一处后端服务不需要重复配。缺点是调试时多了一层需要先确认网关头配没配对。对于个人项目或者小型团队我建议直接用第二种一个Filter 一个允许源列表代码量不大效果清晰。你可以在配置里写好allowed-origins: http://localhost:8080,https://admin.example.com然后在Filter里循环校验命中就反射不命中就忽略。3. 别忽略Cookie侧的SameSite后端配置了也可能白搭3.1 SameSite属性跨站发送Cookie的门禁很多人把CORS配好了withCredentials也设了但浏览器就是不带Cookie。这时候十有八九是栽在SameSite上了。SameSite是Cookie自身的一个属性用来控制Cookie在跨站请求时是否携带。它有三个取值Strict严格模式跨站请求一律不带、Lax宽松模式跨站时只在顶层导航请求中带比如用户从外部链接点进来能带Cookie但如果你的前端用fetch/XHR跨站请求接口不带、None无条件携带但必须配合Secure属性也就是要求HTTPS连接。这里需要分清一个概念跨站cross-site和跨域cross-origin不完全是同一回事。跨站关心的是“站点”也就是域名注册表中的可注册域eTLD1比如a.example.com和b.example.com是同一个站但example.com和evil.com才是跨站。跨域关心的是“源”协议域名端口只要有一个不同就算跨域。在前端localhost:8080调后端localhost:9090的场景里这俩是跨域但同站都是localhost所以SameSite在某些浏览器版本下不太会拦你。但一旦前端是https://app.example.com后端是https://api.example.com这就属于跨站了Cookie的SameSite属性会变成主要的“拦路虎”。在Chrome 80版本之后默认SameSite值从None改成了Lax。这意味着如果后端设置Cookie时没有显式声明SameSite浏览器会按Lax处理跨站XHR请求统统不带Cookie。所以生产环境跨域登录配置里后端设置Cookie时几乎必须显式设置SameSiteNone; Secure不然CORS配得再好也无济于事。3.2 开发环境实战本地跨域调通的配置模板开发场景比较特殊。前端跑在http://localhost:8080后端跑在http://localhost:9090这属于跨域但同站。因为在Chrome的站点定义里localhost:8080和localhost:9090算同一个站所以SameSiteLax不会拦Cookie发送但CORS那套还是必须配的。也就是说本地联调时你只需要把CORS的Credentials和Origin配好前端设credentials: include就行localhost之间传Cookie问题不大。不过有个坑Chrome对SameSiteNone的Cookie强制要求Secure而Secure的Cookie只在HTTPS或者localhost下才会被发送。所以你如果给Cookie设了SameSiteNone; Secure在本地用http://localhost环境是能用的浏览器把localhost当安全上下文但如果你用http://192.168.x.x这种局域网IP调试SecureCookie会被直接拒绝这就是热词里说的“the request client is not a secure context”的常见来源之一。解决方法是本地联调时如果后端跑在IP上就不要设置Secure或者用localhost访问。顺带说一句如果你实在需要在一个非HTTPS的局域网IP环境里完整模拟跨域Cookie最快的办法是在Chrome里把那台机器的IP加入“不安全来源视为安全来源”的flag列表地址栏输入chrome://flags/#unsafely-treat-insecure-origin-as-secure加入http://192.168.1.100:9090这样的地址重启浏览器。这个办法只适合开发调试不要在生产环境用。我是每次换网络环境都要重新配一次有点烦但属实的省事。3.3 Cookie的Secure、Path、Domain属性排查最后补充一个排查维度Cookie的Domain和Path属性也会影响能否被写入和携带。如果后端设置Cookie时指定了Domainexample.com那只有请求example.com及其子域时浏览器才考虑发送它前端域名不在这个Domain范围里Cookie写了也白写。反过来如果前端是admin.example.com后端是api.example.com那后端设置Domainexample.com是合理的因为这样两个子域都能读到同一个Cookie。Path同理Path/表示全站可用Path/api就只在请求路径匹配/api前缀时携带。生产环境做跨子域登录我建议后端显式设置Domain为公共根域Path/SameSiteNoneSecure。这个组合是跨域场景下最不折腾的配置。还有一个容易忽视的细节修改Cookie的SameSite或Domain后浏览器不会自动删除旧的同名字Cookie。旧Cookie还占着位置如果它的路径或者域名范围和新增Cookie不一样浏览器可能同时存在多份同名Cookie取哪份按最精确匹配来。这就会导致改完配置后测试依然失败清清Cookie再试一次往往就好了。4. 实操三种常见后端框架的CORS Cookie配置4.1 Spring BootJava/前后端分离登录Spring Boot是Java后端最常见的框架处理CORS有几种方式我推荐用WebMvcConfigurer加CorsRegistry的方式配置直观也好维护。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOrigins(http://localhost:8080) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }这里有两个关键点。第一allowedOrigins不能是*必须写具体地址因为allowCredentials(true)和通配符Origin是冲突的。第二allowedHeaders(*)在这里没问题你可以放宽请求头只要方法列表里包含OPTIONS就行预检请求走的就是它。如果前端域名不止一个可以用allowedOrigins传多个值或者用allowedOriginPatterns配合通配符模式。allowedOriginPatterns(*)在Spring Boot 2.4之后允许和allowCredentials(true)共存但本质上它返回的仍然是精确Origin只是配置层面支持了通配匹配比手写反射安全得多。我个人建议能用allowedOriginPatterns就别自己写Filter。后端设置Cookie时注意SameSite。Spring Boot里可以通过配置server.servlet.session.cookie.same-sitenone来设置SameSite但需要Spring Boot 2.6及以上版本并且Secure也要配合设置。如果是手动创建Cookie直接这样写Cookie cookie new Cookie(session_id, sessionId); cookie.setHttpOnly(true); cookie.setSecure(true); // 生产环境必须本地IP调试时先注释 cookie.setPath(/); cookie.setDomain(example.com); cookie.setAttribute(SameSite, None); response.addCookie(cookie);4.2 Node.js/ExpressNode.js生态里cors中间件是最常用的方案。可以看下官方的README核心配置如下const cors require(cors); app.use( cors({ origin: http://localhost:8080, methods: [GET, POST, PUT, DELETE, OPTIONS], allowedHeaders: [Content-Type, Authorization, X-Requested-With], credentials: true, maxAge: 3600 }) );cors中间件的origin可以接收一个函数用于动态判断是否放行适合做白名单反射const allowedOrigins [http://localhost:8080, https://admin.example.com]; app.use( cors({ origin: function (origin, callback) { if (!origin || allowedOrigins.includes(origin)) { callback(null, true); } else { callback(new Error(Not allowed by CORS)); } }, credentials: true }) );注意我用!origin做了一次放行处理这是为了避免同源请求或非浏览器请求比如Postman、curl因为没有Origin头而被拦截。如果你希望所有非浏览器客户端都能访问这个判断是必要的。Cookie设置上Express里最常用的是cookie-parser配合res.cookie()res.cookie(session_id, token, { httpOnly: true, secure: true, // 生产环境HTTPS必须 sameSite: none, // 关键属性跨站携带必须 domain: .example.com, path: /, maxAge: 24 * 60 * 60 * 1000 });sameSite: none和secure: true是绑定的只写前者不写后者Chrome会直接拒绝这个Cookie。但如果你在本地HTTP环境测试secure: true又会变成阻碍所以一个常见的处理方式是根据环境变量动态切换const isProduction process.env.NODE_ENV production; res.cookie(session_id, token, { httpOnly: true, secure: isProduction, sameSite: isProduction ? none : lax });4.3 FastAPIPythonPython后端这几年FastAPI越来越流行CORS配置用CORSMiddleware。它的参数名和Spring Boot对照着看特别好记但有一处“坑”是很多新手绕不过去的from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[http://localhost:8080], allow_credentialsTrue, allow_methods[*], allow_headers[*], )如果allow_origins里写了*同时allow_credentialsTrueFastAPI会直接抛一个运行时错误。它要求你必须提供具体来源列表才能开启凭据。如果你确实想动态反射来源可以在allow_origin_regex里写正则而不是用*app.add_middleware( CORSMiddleware, allow_origin_regexrhttps?://(localhost|127\.0\.0\.1)(:\d)?, allow_credentialsTrue, allow_methods[*], allow_headers[*], )FastAPI设置Cookie的方式也很直接用Response.set_cookiefrom fastapi import Response app.post(/login) def login(response: Response): response.set_cookie( keysession_id, valuetoken, httponlyTrue, secureIS_PRODUCTION, samesitenone if IS_PRODUCTION else lax, domain.example.com if IS_PRODUCTION else None, path/ ) return {code: 0}4.4 前端fetch与Axios的关键配置后端配完前端如果不配合照样白搞。浏览器的请求在默认情况下是不带跨域Cookie的必须显式打开凭证开关。用原生fetch要在请求里加credentials: includefetch(https://api.example.com/api/user, { method: GET, credentials: include, headers: { Content-Type: application/json } })用Axios要在请求配置里设置withCredentials: true。注意这个配置要放在全局Axios实例上否则每个请求都要写一遍import axios from axios; const http axios.create({ baseURL: https://api.example.com, withCredentials: true // 关键跨域携带Cookie });设置完之后在浏览器里打开Network面板点进登录请求如果一切正常你会在Request Headers里看到Cookie: session_idxxx在Response Headers里看到Set-Cookie和Access-Control-Allow-Credentials: true。这俩都出现跨域Cookie才算真正打通。5. 常见报错与排查技巧实录5.1 报错速查表把后台问得最多的几种报错整理成了表格遇到类似问题直接对号入座。报错信息原因解决方案has been blocked by cors policy: no access-control-allow-origin header is present服务端没返回CORS头或者Origin不在白名单内检查后端CORS配置确认Access-Control-Allow-Origin是否包含当前请求源The value of the Access-Control-Allow-Origin header in the response must not be the wildcard * when the requests credentials mode is include使用了*通配符 withCredentials改成具体源配合allowCredentials(true)request header field authorization is not allowed by Access-Control-Allow-Headers in preflight response预检请求携带了服务端未允许的请求头在Access-Control-Allow-Headers里加上Authorization等自定义头the request client is not a secure context请求源被浏览器判定为不安全上下文常见于SameSiteNone 非HTTPS/IP环境本地用localhost访问生产配HTTPS接口返回成功但Application里没有Cookie服务器设置了Set-Cookie但浏览器因SameSite、Secure或跨域策略拒绝写入检查Cookie属性SameSiteNone时必须有SecureDomain是否匹配前端是否有credentials: include预检请求OPTIONS返回404后端框架自动处理了CORS但路由没有覆盖OPTIONS请求确认框架CORS中间件加载顺序或显式处理OPTIONS请求5.2 排查工具箱CORS的问题很多时候一眼看不出根源我建议按下面的顺序排查第一步开Chrome DevTools的Network面板找到那个被Block的请求点击看Response Headers。先确认服务端到底有没有返回Access-Control-Allow-*系列头。如果完全没有问题在后端如果有但不符合要求浏览器会标记出来按提示去改。第二步用curl模拟请求看服务端响应头长什么样。curl不带Origin头看不出跨域效果可以手动加curl -X OPTIONS http://localhost:9090/api/user \ -H Origin: http://localhost:8080 \ -H Access-Control-Request-Method: GET \ -H Access-Control-Request-Headers: content-type \ -i这样可以看到服务端对于预检请求返回的CORS响应头如果服务端没返回Access-Control-Allow-Origin那问题一定在后端前端改多少遍都没用。第三步检查浏览器Application面板的Cookies标签看目标域名下到底有没有Cookie存在以及它的SameSite、Secure、Domain值。很多问题在这一步就能看到答案Cookie存在但没有SameSiteNone标记或者Domain不对一目了然。第四步如果以上都正常就用“隐身窗口”重测一次。为什么强调隐身窗口因为已有的Cookie缓存可能掩盖或干扰问题隐身模式是一个干净的Cookie环境能精准还原首次登录的完整链路。5.3 我踩过的三个坑第一个坑是“本地能过生产不能过”。原因是本地是localhost跨端口访问被浏览器视为同站SameSiteLax不影响但生产环境是app.example.com请求api.example.com跨站SameSiteLax直接把Cookie扣住了。这个坑坑了我整整一个下午最后发现只是少写了一个SameSiteNone; Secure。第二个坑是“Nginx层把Origin头吞了”。后端配置全对但Nginx反代时在proxy_pass前没有加proxy_set_header Origin $http_origin导致后端读到空的Origin反射逻辑返回不了CORS头。排查了很久才发现是网关层的问题所以提醒大家如果项目里存在Nginx或网关排查范围一定要包含这一层。第三个坑是“通配符跨域跑通后又偷偷改成精确源导致接口在部分浏览器上报错”。之前项目为了省事allow_origins一直用*后来加了Cookie需求把Origin改成了具体域名结果老用户因为浏览器缓存了旧的预检响应一会能用一会不能用。这时候要清Cache、清预检缓存。浏览器对OPTIONS预检响应是按max-age缓存的如果配置了maxAge: 3600改配置后要等一小时缓存过期或者直接强制刷新清缓存才能生效。在这里我再补充一个安全提醒跨域Cookie打通之后CSRF跨站请求伪造的风险会上升。CORS Cookie本身是浏览器机制攻击者没法直接跨域读取你的接口数据但如果你接口只靠Cookie做认证攻击者可以构造一个自动提交的跨站请求比如一个隐藏表单让浏览器带着你的Cookie去请求接口。所以生产环境建议做好CSRF Token校验或者把关键接口改成非Cookie认证比如Authorization头方式。这也是为什么很多现代项目选择用Token放在Header里而不是依赖Cookie其中一个重要原因就是CSRF面更小。另外Access-Control-Allow-Credentials: true一定要按需开启。如果你只是普通的公开接口完全没有必要开这个头因为一旦开启就要求Origin必须是精确匹配而且任何一个白名单源的XSS漏洞都可能被利用来发起带凭证的跨域请求。开Credential之前反问自己三遍我的接口真的需要Cookie吗不能换成Authorization头不能做成同域部署确认需要再开。最后分享一个判断思路如果项目是全新的我建议优先考虑“同域部署 依赖Cookie”或者“跨域部署 用Token认证”这两种方案都比“跨域 Cookie”心智负担小得多。确实需要跨域Cookie的场景一般集中在SSO单点登录、统一身份认证这类系统中这种场景下CORS的配置就不是“能通就行”而是要当成安全基座来对待——白名单收紧、预检缓存合理设置、Cookie属性合规每一项都值得认真核对。我个人在实际操作里的体会是CORS Cookie这套组合百分之八十的问题发生在“你以为两边都配好了”但实际上两边各差一个参数。前端少了credentials: include后端少了Access-Control-Allow-Credentials: true或者Cookie少了SameSiteNone任何一个缺失链路都走不通。排查的时候只要按照“请求头 → 响应头 → Cookie属性”这条线从上到下捋一遍基本几分钟就能定位。希望这篇文章能帮你少走点弯路。