浏览器报 CORS 错,先别怪后端:前端先看懂的跨域排查实战
前端调自己后端却报 CORS 错,请求可能根本没发出去。本文按 MDN 同源策略与 CORS 官方文档讲清楚:源的三件套、写嵌读三类交互、简单请求与预检、带凭证时星号为什么失效,附五步排查法与五个反模式。

先把这篇的边界说清楚。站里已经有一篇《Web 安全基线实战》,讲的是 CSP、CSRF、XSS、SQL 注入——那篇讲的是“别让攻击进来”,是防守。而这篇讲的是另一个方向:你自己的前端去调你自己的后端,浏览器凭什么拦下来。还有一篇《API 弹性实战》讲超时、重试、熔断、降级,那篇的前提是“请求发出去了、后端出问题了”;这篇的前提更靠前——请求根本没发出去,或者发出去了、响应回来了,浏览器却不让你读。这两种“不行”看起来都是报错,修法完全不一样,混在一起查,一下午就没了。
下面用到的“云端花市”是一个虚构的练手项目:一个卖花的线上小摊,前端跑在本地 5173 端口,后端接口在另一个域名上。本文所有以它为例的操作、代码和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于同源策略与 CORS 的规则、头字段名和行为,都来自 MDN 的同源策略与 CORS 官方文档,来源见每篇的 meta 信息与 evidence 记录。MDN 文档里的 foo.example 与 bar.other 也是文档自带的示例域名,不是真实网站。
先搞清“源”是什么:协议、主机、端口三件套
浏览器判断两个地址是不是“一家人”,只看三样东西:协议、主机、端口。这三样全一样,才叫同源;差一样,就是跨源。MDN 同源策略文档里拿 http://store.company.com/dir/page.html 当基准,给了一张对照表,特别直观:换个路径 dir2/other.html,还是同源,因为只差路径;换成 https,跨源,因为协议不同;换成 81 端口,跨源,因为 http 默认是 80 端口;换成 news.company.com,跨源,因为主机不同。子域名也不行——news 和 store 看着像一家人,在浏览器眼里就是两家。
这张表值得背下来,因为 vibe coding 里最常见的跨域就是自己造出来的:前端本地开发跑在 localhost:5173,后端跑在 localhost:3000,主机一样、协议一样,端口不同,就是跨源。还有一种常见情况:本地用 http,上线用 https,协议一换,昨天还好好的请求今天就报跨域。先对着三元组看一眼,很多“突然不行了”其实是部署时换了其中一件。
还有两个冷门但容易踩的坑。第一,用 file:// 直接双击打开本地 HTML 文件时,现代浏览器一般把它的源当成“不透明源”——同一个文件夹里的文件也不算同源,照样可能报 CORS 错。本地预览别双击文件,起一个本地服务器再测。第二,document.domain 这个老办法已经废弃了,MDN 文档里明确标着警告:它会破坏同源策略提供的安全保护,还会带来兼容问题和安全漏洞。AI 生成的老代码里偶尔还会出现这一行,见到了就删掉,别留着。
写、嵌、读:浏览器只拦“读”
同源策略把跨源互动分成三类:写、嵌、读。跨源“写”通常是允许的,比如点一个链接跳过去、表单提交到别的域名、页面重定向。跨源“嵌”通常也是允许的,比如用 script 标签引第三方的 JS、用 link 引第三方的 CSS、用 img 标签显示别站的图片、用 video 播别站的视频、用 iframe 嵌别人的页面。跨源“读”通常是不允许的:你的 JS 不能直接去读别站返回的数据。
这个区分很关键,因为它解释了为什么“图片能显示、接口却读不到”。图片是嵌进去的,浏览器只负责显示,不让你用 JS 读它的像素;接口返回的 JSON 是要读进你的代码里用的,浏览器就得管。反过来也解释了为什么 CORS 报错不是“请求被拦了”——很多时候请求其实已经发出去了,服务器也正常返回了,是浏览器收到响应之后、交给你代码之前,把它扣下了。你的后端日志里能看到这条请求,后端同学说“我这边 200,没问题”,前端却报红,两边都没说谎,拦人的那道关在浏览器手里。
那 CORS 到底是干什么的?MDN 的说法很直白:CORS 是 HTTP 的一部分,让服务器告诉浏览器“哪些别的源可以读我的东西”。它不是给浏览器开后门,而是让服务器在响应里贴一张放行条:Access-Control-Allow-Origin。没有这张条子,浏览器默认不放行;有了,浏览器才把响应交给你。主语一直是服务器,前端能做的只是“按规矩发请求”,改不了放行规则。
简单请求:不用预检的那种
有些跨域请求不用先打招呼,直接发就行,MDN 把它们叫做简单请求。要同时满足几个条件才算简单:方法只能是 GET、HEAD、POST 三种之一;能手动设置的请求头只能是 Accept、Accept-Language、Content-Language、Content-Type、Range 这几个安全清单里的;Content-Type 还只能是三种值之一:application/x-www-form-urlencoded、multipart/form-data、text/plain;用 XMLHttpRequest 时不能监听上传进度;请求里不能用 ReadableStream。
拿 MDN 的例子走一遍就明白了。foo.example 上的页面要从 bar.other 取一段 JSON,写一句 fetch("https://bar.other"),浏览器发出去的请求里会带一个 Origin: https://foo.example,告诉服务器“我是谁”。服务器回 200,响应头里带 Access-Control-Allow-Origin: *,意思是“任何源都能读”。想只放行一家,就把星号换成具体的源:Access-Control-Allow-Origin: https://foo.example。整件事就这两行头,一行问、一行答。
这里有两个新手最容易误解的点。第一,星号不是万能钥匙,它只对“不带凭证”的请求有效;一旦请求带了 Cookie 或登录信息,星号就不管用了,后面凭证那节细说。第二,别在前端代码里手动加 Access-Control-Allow-Origin 这个头——它是服务器的响应头,前端加了没用,还会因为多了一个自定义头,把本来简单的请求变成需要预检的请求,越修越糟。

预检请求:浏览器先发一封问询信
只要请求“不简单”,浏览器就不会直接发,而是先发一封问询信:用 OPTIONS 方法问服务器“我接下来想这么发,你接不接受”。这封问询信就叫预检请求。什么情况下会触发预检?方法不是 GET、HEAD、POST,比如 PUT、DELETE;Content-Type 是 application/json——注意,application/json 不在上面那三种简单值里,所以前端调接口最常见的 POST JSON 默认就会预检;或者带了一个自定义头,比如 Authorization、X-PINGOTHER 这种。
MDN 的预检例子值得跟着读一遍。foo.example 想往 bar.other 发一个 POST,Content-Type 是 text/xml,还带了一个自定义头 X-PINGOTHER。浏览器先发 OPTIONS,带上两个头:Access-Control-Request-Method: POST,告诉服务器“我接下来要用 POST”;Access-Control-Request-Headers: content-type,x-pingother,告诉服务器“我接下来要带这两个头”。服务器回 204,带上 Access-Control-Allow-Origin: https://foo.example、Access-Control-Allow-Methods: POST, GET, OPTIONS、Access-Control-Allow-Headers: X-PINGOTHER, Content-Type、Access-Control-Max-Age: 86400。意思是:方法可以、头可以,这个答复 86400 秒(也就是 24 小时)内有效,不用每次都来问。之后浏览器才发真正的 POST,而且真正的 POST 里不再带那两个 Access-Control-Request-* 头——它们只属于问询信。
关于预检,有三条经验。第一,预检的默认有效期只有 5 秒,服务器可以用 Access-Control-Max-Age 延长,但每个浏览器还有自己的上限,设得再大也不会无限有效。第二,预检请求本身永远不带凭证,MDN 明确写了这一条;想让“带凭证的正式请求”通过,服务器要在预检响应里写 Access-Control-Allow-Credentials: true。第三,预检之后如果服务器返回重定向,有的浏览器会直接报错,MDN 的建议是改服务端、别让预检撞上重定向,或者把请求改回简单请求。本地开发时最常见的预检报错,其实是后端根本没处理 OPTIONS 方法——后端框架没配跨域中间件,OPTIONS 直接 404,浏览器就停在问询这一步,正式请求一次都没发过。
带凭证的请求:星号在这里失效
默认情况下,跨域的 fetch 和 XMLHttpRequest 不会带凭证,Cookie 和 HTTP 认证信息都不会跟着走。想带上,前端要显式说一声:fetch 里写 credentials: "include",XMLHttpRequest 里把 withCredentials 设成 true。光前端说了还不够,服务器也得点头:响应里必须带 Access-Control-Allow-Credentials: true,不然浏览器会直接把响应扔掉、不交给你的代码。注意这个顺序:请求发出去了、响应也回来了,是浏览器在最后一步决定“不给你看”。
凭证一进来,星号就全面失效,MDN 用了四个“必须不能”:响应带凭证时,Access-Control-Allow-Origin 不能写星号,必须写明确的源;Access-Control-Allow-Headers 不能写星号,必须列出具体的头名;Access-Control-Allow-Methods 不能写星号,必须列出具体的方法;Access-Control-Expose-Headers 也不能写星号,必须列出具体的头名。AI 生成的后端代码最爱在这里翻车:前端一说要带 Cookie,后端图省事回一个星号,浏览器照样拦,控制台还会补一句“通配符不能用于带凭证的请求”。修法不是前端改,而是后端把星号换成前端真实的源,并且在响应里加上 Vary: Origin——因为同一个接口要对不同的源回不同的放行头,缓存必须按源区分,不然 A 站的放行头会被缓存下来发给 B 站。
还有一层是服务器管不着的:第三方 Cookie 政策。就算服务器全都放行了,浏览器也可能因为自己的第三方 Cookie 设置,根本不把 Cookie 发出去,或者收到 Set-Cookie 也不保存。MDN 提醒,Set-Cookie 只有在 Allow-Origin 是明确源而不是星号时才会生效,而且 Cookie 的 SameSite 属性、各浏览器的默认策略都会插手。所以“本地能登录、上线登不上”时,别只查 CORS 配置,也看一眼浏览器对第三方 Cookie 的态度。
排查五步:按顺序查,别乱试
跨域报错最折磨人的地方,是 JS 只能知道“出错了”,具体错在哪,MDN 说得很明白:出于安全原因,报错细节不会交给 JS,唯一能看到具体原因的地方是浏览器控制台。所以第一步永远是打开控制台,看浏览器原话,而不是对着自己的代码瞎猜。控制台会写清楚是哪一种:是没有放行头、预检没通过、还是凭证和星号冲突。
第二步看 Network 面板。找到那条发红的请求,先看它前面有没有一条 OPTIONS 请求。如果有 OPTIONS、并且 OPTIONS 本身就红了,问题在预检:要么后端没处理 OPTIONS,要么 Allow-Methods 或 Allow-Headers 里没放行你要用的方法或头。如果没有 OPTIONS、直接就是正式请求红了,问题在简单请求这一层:看响应头里有没有 Access-Control-Allow-Origin、值对不对。Chrome 开发者工具的 Network 面板截图里,一条失败的请求会直接标红,点进去看响应头,答案一般就在那里。
第三步,对照三张表逐一核对:你的请求是不是简单请求(方法、头、Content-Type 三项);服务器的放行头是不是三件套齐全(源、方法、头);带凭证的话,四条“不能用星号”是不是都守住了。九成问题出在这三张表里,不用动架构。
第四步才是想办法。本地开发最干净的办法,是让前端开发服务器做同源代理:浏览器只跟同源的前端服务器说话,由它把接口请求转发给后端,浏览器眼里全程都是同源,跨域问题根本不存在。等上了线,前后端同域部署当然最好;做不到,就在后端配好白名单,只放行你自己的前端域名。千万别图省事给浏览器加 --disable-web-security 之类的启动参数,或者装个“关掉 CORS”的插件——那只是在你自己的电脑上把门拆了,用户的浏览器照样拦,而且等于把自己的浏览器置于不设防的状态。
第五步,上线之前过一遍检查清单:生产环境的 Allow-Origin 是不是只写了自己的域名、没有残留星号;带 Cookie 的接口是不是写了 Allow-Credentials: true 并且 Origin 是明确值;Vary: Origin 加了没有;OPTIONS 是不是正常返回 204 而不是 404;预检缓存时间是不是合理。云端花市这个虚构项目上线前就是按这五条过的,第一条就查出后端配置里还留着开发时图方便写的星号,改掉之后,带登录的下单接口才真正通了。
三个真实报错长什么样:对着控制台原话认错
控制台的报错看着都像天书,但其实就三种句式,对上号就知道该修哪边。第一种句式是“没有放行头”:控制台会写,没有 Access-Control-Allow-Origin 这个头,或者这个头的值不包含你的源。意思很直接:服务器根本没放行。后端没配跨域中间件、配了但只放行了生产域名、开发用的本地源不在白名单里,都会报这一种。修法在后端:把你的前端源加进白名单,或者开发时走同源代理。
第二种句式是“预检没通过”:控制台会写,预检请求的响应没通过检查,或者干脆说预检失败。这时候先看 Network 里的 OPTIONS 请求:它返回 404,说明后端没处理 OPTIONS;它返回 200 但 Allow-Methods 里没有你要的方法,或者 Allow-Headers 里没有你要的头,说明白名单配窄了。云端花市这个虚构项目第一次联调时报的就是这一种:后端配了 GET 和 POST,忘了 PUT,改菜谱信息的请求每次都死在预检上,正式请求一次都没发过。
第三种句式是“凭证和通配符冲突”:控制台会写,带凭证的请求里,Access-Control-Allow-Origin 不能是通配符。这句话是三句里最友好的,因为它直接把修法告诉你了:把星号换成明确的源,再补上 Allow-Credentials: true。还有一种变体:响应里明明有放行头,但浏览器还是拦,原因是响应头里根本没有 Allow-Credentials,而你的请求带了 credentials: "include"。三句话对上号,修哪边、改哪行,基本就不用猜了。
五个反模式
反模式一:后端回星号、前端带 Cookie。这是最常见的组合错,两边各写各的,凑在一起就拦。记住一条铁律:带凭证就不能用星号,没有例外。
反模式二:在前端手动加 Access-Control-Allow-* 的头。这是响应头,不是请求头,前端加了只会让请求变复杂、多一次预检,问题一个没解决。
反模式三:预检一报错就改成 text/plain 绕过去。把 Content-Type 改成简单值确实能躲掉预检,但后端按 JSON 解析就会出错,等于把一个明确的报错换成一个更难查的错。绕过预检不是修好,是把问题藏起来。
反模式四:把 CORS 当 CSRF 防护。CORS 管的是“浏览器让不让你的 JS 读响应”,CSRF 防的是“别人替你的用户发请求”。MDN 同源策略文档里写得很清楚:防跨源写,要用不可猜测的 token;这两件事各管各的,配好了 CORS 不等于防住了 CSRF。
反模式五:拿 CORS 代理当正式方案。开发时临时用个公开代理转发请求可以救急,但把它写进生产代码,等于把用户的请求和 Cookie 交给一个第三方去转手,慢、不稳定、还不安全。正式环境要么同域、要么后端自己配白名单。
检查表:下次报跨域,先过一遍
报错之后:控制台原话是什么?Network 里有没有 OPTIONS?OPTIONS 红了还是正式请求红了?三张表(简单请求条件、放行头三件套、凭证四禁令)逐项对过了没有?后端日志里有没有收到这条请求——收到了,说明拦在浏览器;没收到,说明死在预检。
修的时候:本地开发先上同源代理;后端白名单只写自己的域名;带凭证的接口把星号全换成明确值、补 Vary: Origin;OPTIONS 必须正常响应;别碰 --disable-web-security。
上线之前:生产配置里还有没有开发时留下的星号?预检缓存时间合理吗?换个浏览器、清掉缓存再测一遍,确认放行头不是缓存里的旧答案。跨域报错看着吓人,拆开看无非就是三件事:你是谁(Origin)、我放谁进(Allow-Origin)、这次带不带凭证。按这个顺序查,大多数报错半小时内就能定位。
评论 (0)
原始来源
相关文章
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。
同一个页面要在手机、平板、电脑上都站得住。本文按 MDN 的《Responsive web design》《Using media queries》《viewport meta 参考》三篇官方文档讲清楚:流式 HTML、viewport 标签、流式网格与 max-width、图片不撑破容器、媒体查询语法、按内容定断点、mobile-first、响应式字号、按能力查设备与上线检查清单。
JavaScript 里数字只有一种类型 Number,存成 64 位浮点数,所以 0.1 + 0.2 等于 0.30000000000000004。本文按 MDN 的《Basic math in JavaScript》《Math》《Number》三篇官方文档讲清楚:一种数字类型、浮点误差、钱改成分算、字符串转数字、NaN 与 Infinity、安全整数、四种取整、Math.random、Math 工具箱与显示格式化。