前端跨域问题全解析：同源策略、CORS与反向代理实战

1. 跨域这件事为什么本地跑得好好的一上线就翻车刚入行的头两年我最怕听到的一句话就是“接口在我这边是通的你那边再查查”。明明浏览器地址栏里敲进去能拿到数据Postman 里也一切正常可一旦放到页面里用fetch或者XMLHttpRequest去请求控制台就红成一片报错信息里那个CORS或者Access-Control-Allow-Origin看得人头皮发麻。后来踩的坑多了才明白这不是后端挂了也不是网络不通而是浏览器在中间当了一道“门卫”它执行了一套叫同源策略的规则把不同源之间的请求给拦了下来。所谓跨域本质上是浏览器出于安全考虑限制一个源协议、域名、端口三者组合下的文档或脚本去请求另一个源的资源。注意这里的关键词是“浏览器”服务端之间互相调用是不受这套规则约束的这也是为什么用 Postman 或者 curl 测试永远正常一放进浏览器就出问题的根本原因。很多新手会误以为是接口写错了反复检查参数和路径其实方向从一开始就偏了。这篇文章我想把前端开发里最常撞见的跨域场景掰开揉碎讲清楚。不管你是刚接触前后端分离项目的新人还是已经工作几年但每次遇到跨域都靠“让后端加个头”糊弄过去的老手都能从里面找到能直接抄作业的方案。我会从同源策略的判定逻辑讲起把简单请求和预检请求的区别、几种主流解决方案的适用边界、以及实际项目里最容易踩的坑一条一条说透。内容偏实战代码和配置都能直接拿去改重点在于让你明白每种方案为什么这么设计而不是死记几个响应头。先给个结论定个调跨域没有银弹选哪种方案取决于你的项目架构、部署方式、团队协作模式甚至取决于你能不能改后端代码。下面我会按“先搞懂原理再对比方案最后落地实操”的顺序展开中间穿插我自己踩过的真实坑尽量让每个读到的人都能对号入座。2. 同源策略到底在拦什么把判定逻辑讲成人话2.1 协议、域名、端口三者全等才算同源同源策略的判定标准非常死板就是看协议、域名、端口这三样是不是完全一致。只要有一个不一样就算跨域。我见过不少人以为http://a.com和https://a.com算同一个站实际上协议不同直接跨域也见过有人觉得a.com和www.a.com是一回事但域名不同照样跨域。端口更隐蔽http://a.com默认走 80 端口http://a.com:8080就是另一个源了。这里有个特别容易混淆的点跨域限制的是“读取响应”这个动作而不是“发出请求”这个动作。也就是说浏览器其实把请求发出去了服务端也处理了甚至数据库都改了但浏览器一看响应头里没有允许你这个源访问的标识就把响应内容给藏起来不给你。这就解释了一个经典现象用跨域发一个 POST 请求去创建数据控制台报错说跨域但你去数据库一查数据已经插进去了。这个坑我在早期项目里踩过当时以为是请求没发出去反复重试结果插了一堆重复数据排查了半天才发现是响应被拦了。2.2 简单请求和预检请求两条完全不同的处理路径浏览器把跨域请求分成两类处理方式差别很大理解这个区别是选对方案的前提。简单请求需要同时满足几个条件方法是 GET、HEAD、POST 之一请求头只包含 Accept、Accept-Language、Content-Language、Content-Type 这几个安全字段而且 Content-Type 只能是text/plain、multipart/form-data、application/x-www-form-urlencoded三种之一。满足这些条件的请求浏览器直接发出去服务端返回时带上Access-Control-Allow-Origin头就行浏览器检查通过就把响应交给前端。非简单请求就麻烦了。只要你的请求用了 PUT、DELETE或者 Content-Type 设成了application/json这是前后端分离项目里最常见的又或者自定义了请求头比如带个 token浏览器就会先发一个OPTIONS 预检请求问服务端“我接下来要发一个这样的请求你允许吗”。服务端必须正确响应这个 OPTIONS 请求返回允许的方法、允许的头、允许的源浏览器才会发真正的业务请求。这意味着服务端要处理两次请求一次 OPTIONS 一次真实请求很多后端框架如果没专门配置OPTIONS 请求会直接 404 或者 405前端看到的就是跨域失败。我印象很深的一次排查前端发了个带Authorization头的 POST 请求后端说“我明明加了Access-Control-Allow-Origin啊”结果一看预检请求根本没通过因为后端没处理 OPTIONS 方法。这个点后面讲方案时会反复提到因为它决定了你选哪种方案能真正跑通。2.3 带 Cookie 的请求多了一层凭证限制如果跨域请求需要携带 Cookie 或者 HTTP 认证信息规则会更严。前端必须设置credentials: includefetch或者withCredentials trueXHR同时服务端的Access-Control-Allow-Origin不能是通配符*必须明确指定具体的源而且还要加上Access-Control-Allow-Credentials: true。这三个条件缺一不可少一个浏览器就把响应拦掉。这个限制的设计初衷是防止恶意站点拿着用户的 Cookie 去请求别的站。我在做一个多子域名的后台系统时就被这个坑过主站和子站域名不同登录态靠 Cookie 共享结果跨域请求死活带不上 Cookie排查半天才发现是Access-Control-Allow-Origin写成了*。改成具体域名之后立刻就好了。所以只要涉及登录态方案选择上就要格外小心通配符那套偷懒写法是行不通的。3. 五种主流方案横向对比别再无脑让后端加头了3.1 CORS最正统的方案但配置细节最多CORS跨域资源共享是目前最标准、最推荐的方案它本质上是通过一组 HTTP 响应头来告诉浏览器“这个源可以访问我”。服务端需要设置的核心头有这么几个响应头作用常见取值Access-Control-Allow-Origin允许哪些源访问具体域名或*Access-Control-Allow-Methods允许哪些方法GET, POST, PUT, DELETE 等Access-Control-Allow-Headers允许哪些请求头Content-Type, Authorization 等Access-Control-Allow-Credentials是否允许携带凭证trueAccess-Control-Max-Age预检结果缓存多久秒数如 86400CORS 的优点是标准化、粒度细、支持各种复杂场景缺点就是配置项多任何一个没配对就前功尽弃。比如Access-Control-Allow-Headers里漏了前端实际用到的某个自定义头预检就过不了Access-Control-Max-Age不设的话每次非简单请求都要多一次 OPTIONS 往返性能上也有损耗。3.2 反向代理前端最省心的方案把跨域变成同源反向代理的思路很巧妙既然浏览器只认同源那我让前端请求自己所在的域名再由服务器把这个请求转发到真正的后端去。这样一来浏览器眼里请求的是同源地址根本不触发跨域检查问题从根上消失了。开发环境里最典型的就是各种脚手架自带的 proxy 配置比如 Vite 的server.proxy、webpack devServer 的proxy。生产环境则通常用 Nginx 做反向代理把/api开头的请求转发到后端服务。这个方案的最大好处是前端不用改任何代码后端也不用动只要运维或者部署配置改一下就行。缺点是增加了运维复杂度而且如果代理配置写错排查起来比 CORS 还绕因为浏览器不报跨域了报的是 404 或者 502方向又变了。3.3 JSONP上古方案只适合救急JSONP 是利用script标签不受同源策略限制这个特性来实现的。前端动态创建一个 script 标签src 指向后端接口并带上回调函数名后端返回一段调用这个函数的 JS 代码前端就能拿到数据。它只支持 GET 请求安全性也差现在基本只在对接一些老系统或者第三方接口实在不支持 CORS 时才会用。我个人的态度是新项目一律不考虑老项目能改就改掉。3.4 WebSocket协议不同天然不受同源限制WebSocket 用的是ws://或wss://协议握手阶段虽然会带 Origin 头但服务端可以选择接受或拒绝一旦连接建立后续通信就不受同源策略约束了。如果你的场景本身就是实时通信那用 WebSocket 顺带就绕过了跨域问题。但如果只是为了传个普通接口数据而专门上 WebSocket那就是杀鸡用牛刀得不偿失。3.5 关闭浏览器安全策略只配用来本地调试还有一种“方案”是启动浏览器时加参数禁用同源策略比如给 Chrome 加--disable-web-security。这个做法我必须强调只能用于本地临时调试绝对不能带到任何真实环境。它等于把浏览器的安全防线整个拆掉任何恶意脚本都能随意读取你的数据。我见过有人图省事把这个参数写进了启动脚本结果测试环境一直这么跑属于典型的安全隐患。把这五种方案放一起对比选择逻辑其实很清晰方案适用场景能否改后端支持复杂请求推荐度CORS前后端分离、能改后端能支持高反向代理前端独立部署、不想动后端不需要支持高JSONP对接老系统、只读接口能不支持低WebSocket实时通信场景能支持中关闭安全策略仅本地调试不需要支持极低4. CORS 落地实操从后端配置到前端联调的完整链路4.1 后端配置的三种粒度和常见框架写法CORS 的配置粒度可以粗可以细我一般分三档来理解。最粗的是全局配置所有接口统一放开中间是按路由或控制器配置不同模块用不同策略最细的是单个接口单独设置。实际项目里我推荐按路由配置既能复用又不会一刀切放得太开。以常见的几种后端技术栈为例配置方式差别不小。Node.js 的 Express 可以用cors中间件一行app.use(cors())就能全局放开但要支持带 Cookie 就得传配置对象把origin写成具体域名、credentials设为 true。Java 的 Spring Boot 可以用CrossOrigin注解加在 Controller 上或者写一个全局的WebMvcConfigurer配置类。Python 的 Flask 用flask-cors扩展Django 则可以用django-cors-headers。这里有个特别容易忽略的点预检请求的 OPTIONS 方法必须被放行。很多框架默认只处理业务方法OPTIONS 请求进来直接 405。用中间件方案一般会自动处理但如果是手写过滤器或者拦截器一定要记得对 OPTIONS 请求直接返回 200 并带上 CORS 头不要让它走到业务逻辑里。我踩过一次拦截器里做了登录校验结果 OPTIONS 请求因为没带 token 被拦下来返回 401预检直接失败前端一脸懵。4.2 前端请求侧的配合细节后端配好了前端也不是完全躺平。用 fetch 的时候如果需要带 Cookie必须显式写credentials: include用 axios 的话是withCredentials: true。这个不写浏览器就不会带上凭证后端那边即使配了Allow-Credentials也白搭。还有一个细节是请求头的设置。如果你自定义了请求头比如加了个X-Token那后端的Access-Control-Allow-Headers里必须包含它否则预检过不了。我建议前端在联调阶段把 Network 面板打开专门看那个 OPTIONS 请求的响应头缺哪个补哪个比盲猜快得多。4.3 用 Network 面板定位 CORS 问题的标准流程遇到跨域报错别急着改代码先按这个顺序看一遍 Network 面板找到那条红色的请求看它是 OPTIONS 还是真实方法。如果是 OPTIONS 且状态码不是 2xx说明预检没过问题在后端的预检响应上。点开 OPTIONS 请求的 Response Headers检查Access-Control-Allow-Origin、Allow-Methods、Allow-Headers是否齐全值是否匹配。如果 OPTIONS 通过了但真实请求还是红看真实请求的响应头里Access-Control-Allow-Origin是否存在带 Cookie 时是否写成了具体域名。如果响应头都对但浏览器还是拦检查是不是Allow-Credentials和通配符冲突了。这套流程我用了很多年基本能覆盖九成以上的 CORS 问题。关键是要分清问题出在预检阶段还是真实请求阶段方向对了解决就是几分钟的事。5. 反向代理实操开发环境和生产环境的两套打法5.1 开发环境用脚手架 proxy改完记得重启本地开发时前端跑在localhost:5173后端跑在localhost:8080端口不同就是跨域。这时候最省事的做法是在脚手架配置里加代理。以 Vite 为例在vite.config.js里加这么一段export default { server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } }这段配置的意思是所有以/api开头的请求都转发到localhost:8080并且把路径里的/api前缀去掉。changeOrigin: true会把请求头里的 Host 改成目标地址有些后端会校验 Host不加这个可能被拒。这里有个坑我踩过不止一次改完 proxy 配置必须重启开发服务器热更新不会让代理配置生效。有次我改完配置死活不生效折腾了半小时才发现是没重启白白浪费了时间。另外rewrite要不要写取决于你后端接口的真实路径如果后端本身就有/api前缀那就不用 rewrite写错了会导致 404。5.2 生产环境 Nginx 反向代理的配置要点生产环境一般用 Nginx 做代理核心配置大概是这样location /api/ { proxy_pass http://backend_server/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }这里最容易出错的是proxy_pass末尾那个斜杠。带斜杠和不带斜杠转发后的路径完全不一样。proxy_pass http://backend/会把/api/user转成/user而proxy_pass http://backend会转成/api/user。这个细节坑过无数人包括我。建议配置完一定要用 curl 或者浏览器实测一下真实转发的路径别想当然。还有一个经验是如果前端是单页应用Nginx 里通常还要配一个try_files把非静态资源的请求都指向index.html否则刷新页面会 404。这个和跨域无关但经常和代理配置一起出现顺手提一句。5.3 代理方案下排查问题的思路转换用了代理之后浏览器不再报跨域了但问题可能以另一种形式出现404、502、504。这时候排查思路要换先确认请求有没有到 Nginx再看 Nginx 有没有转发到后端最后看后端有没有正常响应。我一般会看 Nginx 的 access log 和 error logaccess log 能看到请求路径和状态码error log 能看到转发失败的原因。如果 access log 里压根没有这条请求那说明请求没到 Nginx可能是前端请求地址写错了如果有请求但状态码是 502那多半是后端服务没起来或者地址配错了。6. 那些年我踩过的跨域坑六个真实场景复盘6.1 预检请求被登录拦截器挡在门外这个坑前面提过但值得单独展开。当时项目里有个全局拦截器所有请求都要校验 token没 token 就返回 401。结果跨域的非简单请求先发 OPTIONSOPTIONS 请求自然不带 token被拦截器拦下返回 401预检失败真实请求根本没发出去。前端的报错是跨域但根因在拦截器。解决办法是在拦截器里判断请求方法如果是 OPTIONS 就直接放行不做任何校验。这个问题的迷惑性在于报错信息完全指向跨域很容易让人往 CORS 配置上找实际上跟 CORS 头一点关系都没有。6.2 通配符和凭证不能共存Access-Control-Allow-Origin: *写起来最省事但只要请求带了 Cookie浏览器就会拒绝。因为通配符意味着允许任何站点访问如果还允许带凭证那等于任何恶意站点都能拿着用户的登录态去请求接口安全上不可接受。所以带凭证时必须写具体域名。我见过有团队为了图省事把*和credentials: true一起写结果前端一直报跨域查了半天才发现这俩天生互斥。6.3 多个域名白名单的动态匹配有些系统需要允许多个来源访问比如主站、管理后台、移动端 H5 各自的域名。这时候不能简单写死一个也不能用通配符。常见做法是维护一个白名单数组请求进来时读取 Origin 头判断是否在白名单里是的话就把这个 Origin 原样写回Access-Control-Allow-Origin。注意这里有个细节响应头里只能有一个 Origin 值不能把整个白名单都塞进去浏览器只认和当前请求 Origin 完全一致的那个值。6.4 本地 hosts 和域名切换带来的迷惑开发时有时候会改 hosts 文件把某个域名指向本地这时候源就变了原本配好的 CORS 可能突然失效。因为后端白名单里配的是localhost你改成test.local之后就不匹配了。这种问题特别隐蔽因为代码没动、配置没动只是访问地址变了。我的习惯是本地开发尽量统一用localhost需要模拟多域名时再单独处理避免给自己制造混乱。6.5 缓存导致的“改了没生效”浏览器会缓存预检结果由Access-Control-Max-Age控制。如果这个值设得很大比如一天那你后端改了 CORS 配置前端在缓存过期前看到的还是旧结果会误以为改动没生效。排查时可以先在 Network 面板勾选 “Disable cache”或者把 Max-Age 临时调小。这个坑不算常见但一旦遇上很折磨人因为你会反复怀疑自己的配置写错了。6.6 混合内容问题伪装成跨域如果页面是 HTTPS请求的接口是 HTTP浏览器会拦截报的错有时候看起来像跨域实际上是混合内容Mixed Content问题。这个和跨域是两码事解决办法是接口也上 HTTPS或者用代理把 HTTP 接口包一层。区分方法很简单看报错信息里有没有提到 “insecure” 或者 “mixed content”有的话就是混合内容别往 CORS 上找。7. 方案选型的决策树三分钟定下用哪种7.1 先问三个问题答案直接指向方案面对一个跨域需求我一般先问三个问题基本就能定下方案第一个问题能不能改后端代码能改优先考虑 CORS因为它是标准方案粒度细、可控性强。不能改比如对接第三方接口那就只能走代理或者 JSONP。第二个问题前端和后端是不是同一个部署体系如果是同一个 Nginx 下直接配反向代理最省事前端代码一行不用动。如果是完全独立的部署那 CORS 更合适。第三个问题请求是否涉及登录态和复杂方法涉及的话CORS 要配全代理方案天然支持JSONP 直接排除。7.2 不同团队规模下的推荐组合小团队、快速迭代的项目我推荐开发环境用脚手架 proxy生产环境用 Nginx 反向代理前端完全不用关心跨域后端也不用改。这套组合上手快出问题也好排查。中大型团队、前后端职责分明的情况推荐用 CORS由后端统一维护跨域策略前端按规范设置请求头。这样职责清晰跨域策略作为后端的一部分被管理起来不会散落在各处。对接外部第三方接口的场景如果对方支持 CORS 那最好不支持的话就在自己的服务端做一层代理转发把跨域问题收敛到自己可控的范围内而不是让前端去硬扛。7.3 一个容易被忽略的兜底思路不管选哪种方案我都建议在项目里留一个统一的请求封装层把 baseURL、请求头、错误处理都收口到一处。这样万一跨域策略变了改一个地方就行不用满项目找散落的请求代码。这个习惯看起来和跨域无关但实际能省下大量排查时间因为跨域问题往往和请求配置纠缠在一起收口之后定位范围小了很多。8. 上线前的跨域自查清单跨域问题有个特点本地开发环境往往因为各种代理配置而“看起来正常”一上线到真实环境就暴露。所以上线前做一轮自查很有必要。我整理了一份自己常用的清单逐条过一遍基本能避免大部分线上事故。确认生产环境的接口地址和前端页面地址是否同源不同源的话跨域方案是否已经配置到位。检查 CORS 的Access-Control-Allow-Origin是否写成了具体域名涉及凭证时绝对不能是通配符。确认预检请求的 OPTIONS 方法在后端被正确放行没有被拦截器或权限校验挡住。检查Access-Control-Allow-Headers是否覆盖了前端实际发送的所有自定义头。如果用了 Nginx 代理确认proxy_pass的路径拼接符合预期末尾斜杠别写错。确认 HTTPS 页面请求的接口也是 HTTPS避免混合内容问题。检查Access-Control-Max-Age的值是否合理太大不利于配置更新太小增加预检开销。这份清单我每次上线前都会扫一眼尤其是涉及新接口或者新域名的时候。跨域问题不难难在它涉及前端、后端、运维三方任何一方疏忽都会导致问题而且报错信息往往指向不明确。把这几条过一遍能省下大量联调时的扯皮时间。最后分享一个我自己的习惯遇到跨域问题第一反应不是改代码而是打开 Network 面板把请求的完整链路看一遍分清是预检阶段还是真实请求阶段出的问题是响应头缺失还是值不匹配。方向对了解决就是几分钟的事方向错了可能折腾一下午还在原地打转。跨域这东西理解了同源策略的判定逻辑剩下的都是配置问题没什么玄学。