1. 从一次真实的线上故障说起跨域不是理论是拦路虎那天下午我正在工位上喝着咖啡突然收到一连串的告警。前端同学在群里我说新上线的H5页面在部分用户的微信里完全白屏控制台一片红全是“Access-Control-Allow-Origin”的错误。后端接口明明返回了200状态码数据也正常但浏览器就是死活不让JavaScript拿到这些数据。这个场景相信不少前后端开发都遇到过它的名字就叫“跨域”。跨域Cross-Origin不是什么高深的算法它其实是浏览器出于安全考虑给JavaScript代码套上的一道“枷锁”。简单来说当你的前端应用比如运行在https://www.your-app.com试图通过XMLHttpRequest或Fetch API去请求另一个来源Origin的资源比如https://api.third-party.com时浏览器会先检查这个请求是否被目标服务器允许。如果服务器没有明确表示“我允许https://www.your-app.com来访问我”浏览器就会拦截这次请求即使服务器已经处理并返回了数据前端JS也拿不到并在控制台抛出我们熟悉的跨域错误。为什么要有这个限制想象一下如果没有这个限制你登录了银行网站A然后不小心访问了一个恶意网站B。网站B的脚本可以在后台偷偷向银行网站A发起请求因为你的浏览器还带着A网站的登录Cookie窃取你的账户信息、进行转账操作而你却毫无察觉。这就是著名的“跨站请求伪造”CSRF攻击的温床之一。因此同源策略Same-Origin Policy作为Web安全的基石被引入而跨域资源共享CORS则是为了在安全的前提下为合理的跨源访问开的一扇“窗户”。所以当你遇到跨域问题时本质上是在和浏览器的安全策略博弈。你的目标不是“干掉”这个策略你也干不掉而是学会如何正确地告诉浏览器“这次跨域访问是经过双方前端页面所在的服务端和目标API服务端协商同意的是安全的。” 接下来我们就从根儿上拆解看看都有哪些方法能打开这扇窗。2. 跨域的本质同源策略与“源”的判定要解决跨域必须先理解什么是“同源”。浏览器判断两个URL是否同源依据的是“协议域名端口”这三要素完全一致。举个例子https://www.example.com/page.html试图请求https://www.example.com/api/data-同源完全没问题。https://www.example.com/page.html试图请求http://www.example.com/api/data-跨域协议不同HTTPS vs HTTP。https://www.example.com/page.html试图请求https://api.example.com/data-跨域域名不同wwwvsapi。https://www.example.com:8080/page.html试图请求https://www.example.com:3000/data-跨域端口不同8080 vs 3000。只要这三者中有任何一个不同浏览器就会将其视为跨域请求并触发同源策略的检查。这里有一个常见的误解很多人以为只有域名不同才算跨域忽略了协议和端口这在本地开发时尤其容易踩坑比如前端跑在http://localhost:3000后端跑在http://localhost:8080端口不同已然跨域。浏览器的同源策略主要限制以下几种行为DOM访问限制不同源的页面无法通过JavaScript访问彼此的DOM如iframe里的内容。数据请求限制即我们最常遇到的通过XMLHttpRequest或Fetch发起的跨域HTTP请求会被浏览器拦截。Cookie、LocalStorage等存储访问限制无法读取不同源站点的存储数据。我们本文聚焦解决的是第2点跨域HTTP请求。浏览器将跨域请求分为两类“简单请求”和“非简单请求”或“需预检的请求”处理方式有细微差别这是理解后续解决方案的基础。简单请求需同时满足以下条件方法为 GET、HEAD、POST 之一。请求头仅包含Accept,Accept-Language,Content-Language,Content-Type值仅限于application/x-www-form-urlencoded,multipart/form-data,text/plain。没有使用ReadableStream对象。对于简单请求浏览器会直接发出请求并在请求头中自动添加一个Origin字段如Origin: https://www.your-app.com。服务器需要检查这个Origin如果允许则在响应头中返回Access-Control-Allow-Origin: https://www.your-app.com或*表示允许任何源。浏览器看到这个响应头才会把响应数据交给前端JS。非简单请求比如用了PUT、DELETE方法或Content-Type是application/json就复杂一些。在发送真正的请求之前浏览器会先用OPTIONS方法发起一个“预检请求”Preflight Request。这个请求的头部会包含Origin、Access-Control-Request-Method真实请求将用的方法和Access-Control-Request-Headers真实请求将用的自定义头。服务器必须正确响应这个OPTIONS请求返回相应的CORS头部如Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Headers浏览器确认通过后才会发出真实的请求。如果预检失败真实请求根本不会发出。很多同学在调试POST请求跨域时发现浏览器发了两个请求一个OPTIONS一个POST第一个OPTIONS失败了就是这个原因。3. 解决方案一CORS - 官方推荐的标准答案CORSCross-Origin Resource Sharing是W3C标准也是目前解决跨域问题最主流、最推荐的方式。它的核心思想是由服务端来控制是否允许跨域访问。前端代码几乎无需改动除了处理错误关键在于后端接口的响应头需要携带正确的CORS字段。3.1 如何在服务端实现CORS实现CORS本质就是在HTTP响应中添加几个特定的头部。以下以几种常见后端技术为例Node.js (Express框架):const express require(express); const app express(); // 使用cors中间件最简单 const cors require(cors); app.use(cors()); // 默认允许所有源 // 或进行精细配置 app.use(cors({ origin: https://www.your-app.com, // 允许的源可以是数组或函数 methods: [GET, POST, PUT, DELETE], // 允许的方法 allowedHeaders: [Content-Type, Authorization], // 允许的请求头 credentials: true, // 允许发送Cookie重要后面会讲 maxAge: 86400 // 预检请求缓存时间秒 })); // 也可以手动为单个路由设置 app.get(/api/data, (req, res) { res.header(Access-Control-Allow-Origin, https://www.your-app.com); res.header(Access-Control-Allow-Credentials, true); // 如果需要带Cookie res.json({ data: some data }); });Spring Boot (Java):import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.CorsRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) // 匹配的路径 .allowedOrigins(https://www.your-app.com) // 允许的源 .allowedMethods(GET, POST, PUT, DELETE) // 允许的方法 .allowedHeaders(*) // 允许的请求头 .allowCredentials(true) // 允许凭证 .maxAge(3600); // 预检缓存时间 } }Nginx (作为反向代理时):在Nginx的server或location配置块中添加location /api/ { # 其他代理配置... proxy_pass http://backend-server; # CORS 配置 add_header Access-Control-Allow-Origin https://www.your-app.com 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; add_header Access-Control-Allow-Credentials true always; add_header Access-Control-Max-Age 1728000 always; # 处理OPTIONS预检请求 if ($request_method OPTIONS) { return 204; } }注意Nginx中使用add_header时要注意继承规则always参数确保在任何响应状态码下都添加头部。处理OPTIONS请求直接返回204No Content是常见做法。3.2 CORS实战中的关键细节与深坑Access-Control-Allow-Credentials: true与Access-Control-Allow-Origin: *的互斥性这是一个极易踩坑的点。当你的跨域请求需要携带Cookie、Authorization头等凭证信息时服务器必须设置Access-Control-Allow-Credentials: true。但是如果设置了credentials: true则Access-Control-Allow-Origin不能为通配符*必须指定明确的、单一的源。否则浏览器会拒绝请求。前端在发起带凭证的请求时也需要设置fetch(url, { credentials: include })或XMLHttpRequest.withCredentials true。预检请求OPTIONS的缓存为了性能浏览器可以缓存预检请求的结果。服务器通过Access-Control-Max-Age头部来指定缓存时间秒。在开发环境为了及时看到配置更改的效果可以将其设置为0。在生产环境可以根据实际情况设置一个合理的值如7200秒/2小时。Vary: Origin 头部的重要性如果你的服务器根据Origin请求头的值动态返回不同的Access-Control-Allow-Origin比如允许多个特定源强烈建议在响应头中添加Vary: Origin。这告诉缓存服务器如CDN响应内容会因Origin头的不同而变化避免错误的缓存导致其他源的请求失败。Nginx配置中的always参数在Nginx中add_header指令默认只在响应码为200, 201, 204, 206, 301, 302, 303, 304, 307, 308时添加头部。如果后端接口返回了错误如4xx, 5xx这些CORS头就不会被添加导致前端即使收到了错误响应也因为跨域问题而无法读取具体的错误信息只能看到一个网络错误。加上always参数可以确保在任何响应状态下都添加CORS头对于调试至关重要。4. 解决方案二Nginx反向代理 - 前端的“障眼法”如果你无法控制后端API服务器的响应头比如使用的是第三方服务或者觉得在每个后端服务上都配置CORS很麻烦那么Nginx反向代理是一个极其优雅且强大的解决方案。其核心原理是让浏览器认为所有请求都是同源的。具体做法是前端不再直接请求https://api.third-party.com而是请求自己同源域名下的一个路径比如https://www.your-app.com/api-proxy/。然后我们在https://www.your-app.com的服务器上配置Nginx将所有发送到/api-proxy/的请求在服务器端后端对后端没有浏览器安全限制转发到真实的https://api.third-party.com。对于浏览器来说它始终是在和https://www.your-app.com通信因此不存在跨域问题。4.1 Nginx反向代理配置详解假设你的前端应用部署在https://www.your-app.com需要代理到https://api.real-service.com。server { listen 443 ssl; server_name www.your-app.com; # SSL证书配置... # 前端静态资源服务配置... location /api/ { # 前端请求这个路径 # 核心代理指令 proxy_pass https://api.real-service.com/; # 注意结尾的斜杠它会将 /api/xxx 映射到 https://api.real-service.com/xxx # 以下是一些重要的代理设置能解决很多隐性问题 proxy_set_header Host $proxy_host; # 将Host头改为目标服务器的host proxy_set_header X-Real-IP $remote_addr; # 传递用户真实IP proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 传递代理链IP proxy_set_header X-Forwarded-Proto $scheme; # 传递原始协议 # 超时设置根据实际情况调整 proxy_connect_timeout 30s; proxy_send_timeout 60s; proxy_read_timeout 60s; # 如果后端服务有重定向需要修正重定向的Location头否则浏览器会跳转到真实后端地址导致跨域 proxy_redirect off; # 或使用 proxy_redirect default; 并配合 proxy_set_header 处理 # 因为现在对于浏览器是同源请求所以通常不需要在这里设置CORS头。 # 除非你代理后的服务还需要被其他域直接访问。 } }前端代码调用示例// 之前跨域 fetch(https://api.real-service.com/user/info, { credentials: include }) // 现在通过Nginx代理同源 fetch(/api/user/info, { credentials: include }) // 注意路径变了且是同源路径4.2 反向代理的进阶技巧与避坑指南路径重写proxy_pass指令结尾的斜杠/非常关键。location /api/配合proxy_pass https://target.com/;会将/api/user代理到https://target.com/user。如果proxy_pass后没有斜杠则会代理到https://target.com/api/user。你可以使用rewrite指令进行更复杂的路径重写。WebSocket代理如果你的应用使用了WebSocketNginx同样可以代理。配置略有不同location /ws/ { proxy_pass http://backend-ws-server; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; # 关键 proxy_set_header Connection upgrade; # 关键 proxy_set_header Host $host; proxy_read_timeout 3600s; # WebSocket连接通常需要更长的超时 }这样前端就可以通过new WebSocket(wss://www.your-app.com/ws/)来建立连接。负载均衡Nginx反向代理的强大之处还在于可以轻松实现负载均衡。你可以在upstream块中定义多个后端服务器然后在location中使用proxy_pass http://backend_cluster;。upstream backend_cluster { server 10.0.0.1:8080 weight3; # weight表示权重 server 10.0.0.2:8080; server 10.0.0.3:8080 backup; # backup服务器当主服务器都宕机时启用 least_conn; # 负载均衡策略最少连接数 } location /api/ { proxy_pass http://backend_cluster; # ... 其他代理配置 }代理缓存对于一些不经常变化的GET请求可以在Nginx层面设置缓存直接由Nginx响应减轻后端压力。proxy_cache_path /path/to/cache levels1:2 keys_zonemy_cache:10m max_size10g inactive60m use_temp_pathoff; location /api/static/ { proxy_cache my_cache; proxy_cache_key $scheme$request_method$host$request_uri; proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m; proxy_pass http://backend_server; }反向代理方案的优缺点优点对前端透明无需改动代码可以统一处理认证、限流、日志、缓存等能隐藏后端真实地址增强安全性。缺点增加了架构的复杂度需要维护Nginx服务器所有流量都经过代理服务器可能成为性能瓶颈和单点故障可通过集群解决后端服务无法直接获取到客户端的真实IP需通过X-Forwarded-For头解析。5. 解决方案三JSONP - 古老但仍有其场景的“奇技淫巧”在CORS标准尚未普及的年代JSONPJSON with Padding是解决跨域数据获取的主流方案。它巧妙地利用了script标签没有跨域限制的特性。5.1 JSONP的工作原理其原理是前端动态创建一个script标签其src指向目标API地址并在URL中通过查询参数通常是callback指定一个全局回调函数名。服务器接收到请求后不是返回标准的JSON而是返回一段JavaScript代码这段代码的内容是调用那个前端指定的回调函数并将真正的JSON数据作为参数传入。当脚本加载并执行时回调函数就会被调用前端也就拿到了数据。前端实现function handleResponse(data) { console.log(收到数据:, data); // 处理数据... } function fetchByJsonp(url) { const callbackName jsonp_callback_ Date.now() Math.random().toString(16).slice(2); window[callbackName] handleResponse; // 在全局定义回调函数 const script document.createElement(script); script.src url (url.includes(?) ? : ?) callback${callbackName}; document.head.appendChild(script); // 脚本加载完成后清理全局函数和script标签 script.onload script.onerror function() { delete window[callbackName]; document.head.removeChild(script); }; } // 调用 fetchByJsonp(https://api.some-site.com/data?user123);服务器端响应以Node.js为例app.get(/data, (req, res) { const data { userId: 123, name: John }; const callbackName req.query.callback; if (callbackName) { // 返回JS代码而非JSON res.type(application/javascript); res.send(${callbackName}(${JSON.stringify(data)})); } else { res.json(data); // 非JSONP请求返回普通JSON } });5.2 JSONP的致命局限与现代应用场景JSONP虽然简单但缺点非常明显仅支持GET请求这是由script标签的特性决定的无法发送POST、PUT等请求也无法设置自定义请求头。错误处理能力弱script标签的onerror事件能捕获到加载失败但如果是服务器成功响应了但返回了错误信息比如调用了一个不存在的函数前端很难优雅地捕获和处理。安全性问题因为它动态执行了来自外部的JS代码如果服务器被攻破返回了恶意脚本前端将直接执行存在XSS风险。因此必须绝对信任JSONP的提供方。不符合RESTful风格通常用于获取数据难以实现完整的CRUD。那么JSONP现在还有用吗有的但场景非常特定兼容极度古老的浏览器如果你的用户群体中仍有相当一部分使用不支持CORS的IE8/9等浏览器JSONP是备选方案。调用一些仅提供JSONP接口的第三方公共服务例如某些天气、股票数据接口它们可能历史悠久只提供了JSONP方式。简单的数据拉取对于只需要GET方法、无需认证、数据量小的简单场景JSONP的快速实现仍有价值。重要提示在现代Web开发中只要后端服务可控应优先使用CORS。JSONP应被视为一种历史遗留的兼容方案而非首选。6. 解决方案四WebSocket - 超越HTTP的跨域通信WebSocket协议提供了全双工、长连接的通信通道。它本身就不受同源策略的限制。这意味着你可以直接从https://www.client.com的页面建立到wss://api.server.com的WebSocket连接而不会触发跨域错误。6.1 为什么WebSocket可以跨域WebSocket握手阶段使用HTTP/HTTPS协议在握手请求中同样会携带Origin头。服务器可以根据这个Origin决定是否接受连接。关键在于这个安全检查是由服务器端逻辑完成的而不是浏览器强制实施的同源策略。浏览器不会像拦截HTTP请求那样拦截WebSocket连接。如果服务器拒绝了连接它会在握手阶段返回一个HTTP错误响应如403连接就无法建立。6.2 WebSocket连接建立与跨域处理前端建立WebSocket连接非常简单const socket new WebSocket(wss://api.another-domain.com/ws); socket.onopen function(event) { console.log(连接已建立); socket.send(Hello Server!); }; socket.onmessage function(event) { console.log(收到消息:, event.data); }; socket.onerror function(error) { console.error(WebSocket错误:, error); }; socket.onclose function(event) { console.log(连接关闭, event.code, event.reason); };服务器端以Node.js ws库为例如何处理跨域虽然浏览器不强制但良好的实践是服务器端应验证Origin。const WebSocket require(ws); const wss new WebSocket.Server({ port: 8080 }); wss.on(connection, function connection(ws, request) { const origin request.headers.origin; const allowedOrigins [https://www.your-app.com, https://dev.your-app.com]; // 简单的Origin检查 if (!allowedOrigins.includes(origin)) { console.log(拒绝来自, origin, 的连接); ws.close(1008, Origin not allowed); // 1008是政策违规状态码 return; } console.log(客户端已连接来自:, origin); ws.on(message, function message(data) { console.log(收到: %s, data); ws.send(服务器回复: ${data}); }); });6.3 WebSocket方案的适用场景与注意事项WebSocket并非用来替代HTTP API解决普通跨域请求的。它适用于需要服务器主动推送或高频双向通信的场景。典型场景实时聊天应用消息的即时收发。在线协作工具如文档协同编辑需要实时同步用户操作。实时数据仪表盘股票行情、赛事比分、服务器监控数据等实时更新。在线游戏玩家状态的实时同步。注意事项连接保持与重连网络不稳定会导致连接中断必须在前端实现自动重连机制。心跳保活为了防止中间网络设备如防火墙、代理因长时间无数据而断开连接需要定期发送心跳包ping/pong。消息协议设计WebSocket传输的是二进制或文本帧你需要自己设计一套应用层协议来区分消息类型、处理粘包/拆包等。通常使用JSON格式。服务器资源每个活跃连接都会占用服务器资源内存、文件描述符在大规模并发时需要优化服务器架构如使用连接网关、分片。与HTTP API共存一个完整的应用通常是WebSocket处理实时部分HTTP API处理常规的CRUD操作。它们可以部署在同一个域名下也可以分开因为WebSocket本身不受跨域限制。7. 其他方案与场景化选择除了上述四大主流方案还有一些特定场景下的解决思路。7.1 postMessage - 跨窗口/跨iframe通信如果跨域发生在不同窗口或iframe之间HTML5的window.postMessage()API是官方解决方案。它允许来自不同源的窗口之间安全地进行数据传递。// 父窗口 (https://parent.com) const childFrame document.getElementById(myIframe).contentWindow; childFrame.postMessage(Hello from parent!, https://child.com); // 子窗口 (https://child.com, 在iframe内) window.addEventListener(message, (event) { // 必须检查来源 if (event.origin ! https://parent.com) return; console.log(收到消息:, event.data); // 可以回信 event.source.postMessage(Hello back!, event.origin); });关键点接收方必须通过event.origin验证消息来源防止恶意网站发送消息。7.2 开发环境下的便捷方案在本地开发时为了绕过跨域方便调试除了配置后端CORS或Nginx代理前端构建工具也提供了便捷的代理功能。Vite: 在vite.config.js中配置server.proxy。export default defineConfig({ server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, // rewrite: (path) path.replace(/^\/api/, ) } } } })Webpack DevServer: 配置devServer.proxy。module.exports { devServer: { proxy: { /api: http://localhost:8080 } } };这些配置只在开发服务器生效原理和Nginx反向代理类似将本地特定路径的请求转发到目标后端服务器。7.3 如何选择一张决策表面对具体问题你可以参考下表做出选择场景推荐方案理由前后端分离你拥有或能修改后端代码CORS标准、灵活、安全是解决跨域API请求的首选和终极方案。调用无法修改响应头的第三方APINginx反向代理在前端服务器层面“伪装”成同源请求对前端透明。需要兼容IE8/9等古董浏览器JSONP在这些浏览器上可能是不二之选但需注意其局限性。需要服务器主动推送、实时双向通信WebSocket专为实时场景设计不受同源策略限制。本地开发环境快速联调构建工具代理或浏览器插件配置简单无需改动生产代码仅用于开发。不同标签页或iframe间通信postMessage浏览器原生API安全可靠。8. 终极心法从根上避免与优雅处理理解了各种解决方案后更高阶的思路是如何从架构设计上减少或优雅地处理跨域问题域名收敛与API网关在项目初期就做好规划尽量让前端应用和API服务部署在同一个主域名下使用不同的路径或子域名。例如前端www.example.comAPIapi.example.com。对于子域名只要主域名相同且协议端口一致可以通过设置document.domain已逐渐废弃或更通用的在服务端为api.example.com设置Access-Control-Allow-Origin: https://www.example.com来解决。更进一步使用API网关统一管理所有后端服务的入口在网关层面统一处理认证、限流、日志和CORS配置后端微服务无需关心跨域问题。善用“预检请求”缓存对于频繁发生的非简单跨域请求如带自定义头的POST请求确保服务器正确设置了Access-Control-Max-Age头部让浏览器缓存预检结果可以显著提升性能。清晰的错误处理无论使用哪种方案前端都必须做好错误处理。对于CORS网络请求可能会因为跨域失败而无法拿到响应体错误信息比较模糊。可以使用try...catch配合fetch或者监听XMLHttpRequest的onerror事件给用户友好的提示。同时确保服务器在出错时4xx, 5xx也返回正确的CORS头以便前端能读取到具体的错误信息进行调试。安全永远是第一位使用CORS时切忌在生产环境使用Access-Control-Allow-Origin: *尤其是当请求需要携带凭证时。务必严格指定允许的来源列表。使用Nginx代理时也要注意防止代理被滥用成为开放代理可以通过allow/deny指令限制访问IP。跨域问题就像Web开发道路上的一道必过的安检门。它看似麻烦实则是保护用户安全的重要机制。作为开发者我们的任务不是逃避或抱怨而是理解其规则并运用正确的工具和方法在安全的前提下构建出体验流畅的现代化Web应用。从最标准的CORS到灵活的Nginx代理再到特定场景的JSONP、WebSocket每一种方案都有其用武之地。掌握它们你就能在面对任何跨域需求时从容地选出最适合的那把钥匙。
