1. 从一次真实的跨域报错说起那天下午我正在调试一个前后端分离的项目。前端是跑在http://localhost:8080的 Vue 应用后端 API 服务部署在http://api.myapp.com:3000。当我点击页面上的一个按钮试图从后端获取用户列表时熟悉的红色错误信息又一次出现在了 Chrome 浏览器的控制台里Access to fetch at ‘http://api.myapp.com:3000/users‘ from origin ‘http://localhost:8080‘ has been blocked by CORS policy: No ‘Access-Control-Allow-Origin‘ header is present on the requested resource.我相信只要是做过前端开发的朋友对上面这段报错信息都不会陌生。它就像一位严格的保安时刻守卫着浏览器数据安全的大门而这位保安的名字就是同源策略。这个策略绝非浏览器的“bug”或“故意刁难”而是现代 Web 安全的基石。简单来说它规定了一个源Origin的文档或脚本在没有明确授权的情况下不能与另一个源的资源进行交互。这里的“源”由协议、域名、端口三者共同决定任何一个不同即被视为不同源。我本地前端应用的源是http://localhost:8080而后端 API 的源是http://api.myapp.com:3000端口和域名都不同跨域请求自然被拦截。那么我们前端开发者日常工作中到底有哪些场景会触发同源策略的拦截面对这些拦截我们手头又有哪些“通行证”可以合法地让不同源之间进行通信这篇文章我将结合自己多年踩坑和填坑的经验为你系统性地拆解同源策略的本质并深入剖析 JSONP、CORS、代理等主流跨域解决方案的原理、适用场景、具体操作以及那些官方文档里不会写的“坑”。2. 同源策略不是限制而是安全护栏在急着寻找跨域解决方案之前我们必须先理解同源策略究竟在保护什么。很多人把它视为开发中的绊脚石但实际上它是防止恶意网站窃取用户数据的核心防线。2.1 同源的判定标准与常见跨域场景所谓“同源”必须满足以下三个条件完全一致协议相同例如都是http或都是https。域名相同例如都是www.example.com。注意www.example.com和example.com被视为不同源。端口相同例如都是80端口HTTP默认或443端口HTTPS默认。如果未指定端口则使用协议的默认端口。只要有一项不同浏览器就会判定为跨源请求并施加限制。限制主要针对以下几类操作AJAX/Fetch 请求这是最常见的场景使用XMLHttpRequest或Fetch API向不同源发送请求会被浏览器拦截。Web 字体通过 CSSfont-face加载不同源的字体文件。Canvas 绘制图片使用drawImage将跨域的图片绘制到 Canvas 上随后调用getImageData等读取像素数据的方法会受限制。WebGL 纹理。localStorage、IndexedDB等客户端存储每个源都有自己独立的存储空间无法直接访问其他源的存储。注意有一些标签天生就具备跨域能力如img、script、link、iframe等。它们可以加载不同源的资源但浏览器限制了脚本对返回内容的访问权限。例如通过script加载的脚本会直接执行但你无法用 JavaScript 读取其内容通过img加载的图片可以显示但你不能用 Canvas 去分析其像素数据除非对方服务器设置了相应的 CORS 头。2.2 为什么需要这个“护栏”一个简单的思想实验假设没有同源策略会发生什么你登录了银行的网站https://bank.com并保留了登录态Cookie。此时你不小心访问了一个恶意网站http://evil.com。这个恶意网站的页面里嵌入了一段 JavaScript 脚本偷偷向https://bank.com/transfer发起一个 POST 请求请求将你的存款转到攻击者的账户。由于你的浏览器里保存着bank.com的登录 Cookie这个请求会“自动”带上你的身份凭证银行服务器很可能认为这是你的合法操作从而执行转账。这就是恐怖的CSRF跨站请求伪造攻击的简化模型。同源策略的存在使得evil.com的脚本无法直接读取bank.com的 Cookie也无法直接向bank.com发起携带其 Cookie 的 AJAX 请求简单请求除外下文会详述从而极大地增加了此类攻击的实施难度。因此同源策略保护的是用户的数据和隐私是 Web 安全的基石。3. 穿越“护栏”的合法途径主流跨域方案深度解析理解了护栏的必要性我们再来看看在合法合规的开发需求下如何安全地穿越它。每种方案都有其特定的工作原理和适用边界。3.1 JSONP一个基于历史遗迹的“巧计”JSONPJSON with Padding是一种非常古老但一度非常流行的跨域方案。它巧妙地利用了script标签可以跨域加载资源的特性。3.1.1 工作原理与实操步骤其核心思想是前端动态创建一个script标签其src指向目标 API 地址并在 URL 中携带一个回调函数名如callbackhandleResponse。服务器端接收到请求后不是返回标准的 JSON而是返回一段 JavaScript 代码这段代码的内容是调用那个前端指定的回调函数并将真正的数据作为参数传入。前端实现示例function handleResponse(data) { console.log(收到数据, data); // 处理数据... } // 动态创建 script 标签 const script document.createElement(script); script.src ‘http://api.other-domain.com/data?callbackhandleResponse‘; document.body.appendChild(script);后端以 Node.js 为例响应// 假设请求 URL 为 /data?callbackhandleResponse app.get(‘/data‘, (req, res) { const data { name: ‘张三‘, age: 30 }; const callbackName req.query.callback; // 返回的是一段可执行的 JS 代码 res.end(${callbackName}(${JSON.stringify(data)})); });服务器返回的内容将是handleResponse({“name”:”张三”,”age”:30})。当浏览器加载并执行这个script时就会自动调用前端的handleResponse函数。3.1.2 JSONP 的致命缺陷与适用场景JSONP 虽然简单但缺点非常明显仅支持 GET 请求这是由script标签的特性决定的。安全性差因为它本质上是在执行一段来自外部的 JavaScript 代码。如果服务器被攻破返回了恶意脚本前端将毫无防备地执行极易导致XSS跨站脚本攻击。这也是为什么现在搜索“jsonp xss”仍然能发现大量安全讨论。错误处理困难难以像 AJAX 那样通过onerror捕获网络错误或超时。因此在现代 Web 开发中JSONP 已不再是首选方案除非你必须对接一个仅支持 JSONP 的、无法修改的古老第三方接口。对于可控的后端应优先使用 CORS。3.2 CORS官方推荐的现代跨域标准CORS跨源资源共享是 W3C 标准属于“官方认证”的跨域解决方案。它需要后端服务器的配合通过在 HTTP 响应头中添加一系列特定的 Header 来告诉浏览器“我允许某个源来访问我”。3.2.1 简单请求与预检请求这是理解 CORS 的关键。浏览器将 CORS 请求分为两类简单请求和非简单请求需预检的请求。简单请求需同时满足以下所有条件方法为 GET、HEAD、POST 之一。请求头仅包含Accept、Accept-Language、Content-Language、Content-Type值仅限于application/x-www-form-urlencoded、multipart/form-data、text/plain。没有使用ReadableStream对象。对于简单请求浏览器会直接发出请求并在请求头中自动添加Origin字段如Origin: http://localhost:8080。服务器需要检查这个Origin如果允许则在响应头中包含Access-Control-Allow-Origin: http://localhost:8080或*表示允许任何源。浏览器看到这个响应头就会放行前端才能拿到响应数据。非简单请求例如使用了 PUT、DELETE 方法或Content-Type: application/json浏览器会先使用OPTIONS方法发起一个“预检请求”。这个请求会携带OriginAccess-Control-Request-Method实际请求将使用的方法Access-Control-Request-Headers实际请求将携带的自定义头服务器必须正确响应这个 OPTIONS 请求返回的响应头需要包含Access-Control-Allow-OriginAccess-Control-Allow-Methods允许的方法Access-Control-Allow-Headers允许的头部Access-Control-Max-Age预检请求结果缓存时间单位秒预检通过后浏览器才会发出真正的请求。3.2.2 后端配置实战与常见坑点以下以 Node.js (Express) 和 Spring Boot 为例展示如何配置 CORS。Node.js (Express) 配置const express require(‘express‘); const app express(); // 使用 cors 中间件推荐 const cors require(‘cors‘); app.use(cors({ origin: ‘http://localhost:8080‘, // 允许的源可以是数组或函数动态判断 methods: [‘GET‘, ‘POST‘, ‘PUT‘, ‘DELETE‘], allowedHeaders: [‘Content-Type‘, ‘Authorization‘], credentials: true, // 允许发送 Cookie对应前端 fetch 需设置 credentials: ‘include‘ })); // 或者手动设置响应头更灵活但繁琐 app.use((req, res, next) { res.header(‘Access-Control-Allow-Origin‘, ‘http://localhost:8080‘); res.header(‘Access-Control-Allow-Methods‘, ‘GET, POST, PUT, DELETE, OPTIONS‘); res.header(‘Access-Control-Allow-Headers‘, ‘Content-Type, Authorization‘); res.header(‘Access-Control-Allow-Credentials‘, ‘true‘); // 允许凭证 if (req.method ‘OPTIONS‘) { return res.sendStatus(200); // 对预检请求快速响应 } next(); });Spring Boot 配置Configuration public class WebConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(“/api/**“) // 配置针对哪些路径 .allowedOrigins(“http://localhost:8080“) .allowedMethods(“GET“, “POST“, “PUT“, “DELETE“) .allowedHeaders(“*“) .allowCredentials(true) .maxAge(3600); // 预检请求缓存1小时 } }常见坑点排查has been blocked by CORS policy: Response to preflight request doesn‘t pass这通常意味着预检请求的响应头不完整或不符合要求。检查服务器是否正确处理了OPTIONS方法并返回了Access-Control-Allow-Headers包含你前端实际发送的头部如Authorization和Access-Control-Allow-Methods。has been blocked by CORS policy: The ‘Access-Control-Allow-Origin‘ header contains multiple values ‘xxx, *‘Access-Control-Allow-Origin头只能有一个值。检查你的后端代码或网关如 Nginx是否重复设置了此头部。不能同时设置多个源或用逗号分隔如果需要允许多个源需要在后端逻辑中动态判断Origin请求头并返回匹配的值。携带 Cookie 失败如果需要跨域请求携带 CookiewithCredentials则服务器端的Access-Control-Allow-Origin不能为通配符*必须指定明确的、与请求Origin一致的值并且需要设置Access-Control-Allow-Credentials: true。前端在 Fetch API 中需要设置credentials: ‘include‘在 Axios 中需要设置withCredentials: true。3.3 开发环境救星前端代理在本地开发时让后端服务为每个前端开发同学都配置 CORS 是繁琐的。此时前端代理是最优雅的解决方案。它的原理是让前端开发服务器如 Webpack Dev Server、Vite充当一个中间人。浏览器向前端服务器发起请求同源前端服务器再将请求转发到真正的后端服务器不同源并将响应返回给浏览器。对浏览器而言它始终是在同源下通信完美避开了跨域问题。3.3.1 Webpack Dev Server 代理配置在vue.config.js或webpack.config.js中module.exports { devServer: { proxy: { ‘/api‘: { // 匹配所有以 /api 开头的请求 target: ‘http://api.myapp.com:3000‘, // 后端 API 地址 changeOrigin: true, // 修改请求头中的 Host 为目标地址的 host虚拟主机场景可能需要 pathRewrite: { ‘^/api‘: ‘‘ // 重写路径去掉前缀 /api } } } } };配置后前端代码中请求/api/users实际上会被代理到http://api.myapp.com:3000/users。3.3.2 Vite 代理配置在vite.config.js中export default defineConfig({ server: { proxy: { ‘/api‘: { target: ‘http://api.myapp.com:3000‘, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ‘‘), } } } });3.3.3 关于 WSL 和 localhost 代理的一个大坑如果你在 Windows 上使用 WSL 进行开发可能会遇到一个典型问题在 Windows 的浏览器中访问localhost:5173Vite 前端但前端请求代理到的后端服务运行在 WSL 的localhost:3000。此时代理可能会失败因为对于 Windows 系统来说WSL 的localhost是另一个网络环境。错误信息可能类似WSL: 检测到 localhost 代理配置但未镜像到 WSL。NAT 模式下的 WSL 不支持 localhost...解决方案不要使用localhost作为代理目标。改用 WSL 分配给虚拟机的 IP 地址或者使用特殊的主机名。在 WSL 终端执行hostname -I获取 WSL 的 IP如172.xx.xx.xx。将代理配置中的target改为http://172.xx.xx.xx:3000。或者使用hostname.local如Ubuntu-20.04.local作为主机名但需要确保网络发现正常工作。3.4 生产环境基石Nginx 反向代理在生产环境中我们通常使用 Nginx 这类高性能 Web 服务器作为反向代理。它不仅可以处理静态文件、负载均衡更是解决跨域的终极方案之一。其原理与开发代理类似用户访问https://www.myapp.com前端当请求 API 路径如/api/xxx时Nginx 将其转发到内部的后端服务集群并将结果返回。一个基础的 Nginx 反向代理配置示例server { listen 80; server_name www.myapp.com; # 前端静态文件 location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; # 支持 Vue/React 路由 History 模式 } # 反向代理 API 请求 location /api/ { proxy_pass http://backend-server-group/; # 后端服务器地址或 upstream 名称 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_set_header X-Forwarded-Proto $scheme; # 如果需要也可以在这里添加 CORS 头部作为另一道保障 add_header Access-Control-Allow-Origin ‘https://www.myapp.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; if ($request_method ‘OPTIONS‘) { add_header Access-Control-Max-Age 1728000; add_header ‘Content-Type‘ ‘text/plain; charsetutf-8‘; add_header ‘Content-Length‘ 0; return 204; } } }通过这种配置浏览器访问https://www.myapp.com/api/users请求被 Nginx 接收并转发给后端后端响应再经由 Nginx 返回。对于浏览器它只与www.myapp.com通信不存在跨域问题。这是生产环境最推荐、最彻底的解决方案将跨域问题在基础设施层解决前后端代码无需做任何特殊处理除了请求地址要写相对路径/api/xxx。4. 特殊场景与进阶问题处理掌握了三大主流方案我们再来看看一些更具体、更棘手的场景。4.1 文件上传的跨域问题文件上传通常使用multipart/form-data格式这属于简单请求吗是的Content-Type: multipart/form-data是简单请求允许的类型之一。所以如果只是简单的表单上传且后端配置了正确的Access-Control-Allow-Origin通常不会触发预检请求。但是如果你需要在上传时携带自定义头部如Authorization令牌或者使用了非简单方法如 PUT那么就会触发预检请求。此时后端必须正确处理OPTIONS请求并在Access-Control-Allow-Headers中包含你的自定义头。前端使用 axios示例const formData new FormData(); formData.append(‘file‘, file); axios.post(‘https://api.other.com/upload‘, formData, { headers: { ‘Authorization‘: ‘Bearer ‘ token, // 自定义头会触发预检 // ‘Content-Type‘: ‘multipart/form-data‘ // 注意不要手动设置这个头axios 会根据 FormData 自动设置正确的 boundary。 }, withCredentials: true // 如果需要携带 Cookie }).then(response { // 处理响应 });后端配置需要确保Access-Control-Allow-Headers包含Authorization。4.2 WebSocket 连接跨域WebSocket 协议本身不受同源策略限制。浏览器在发起 WebSocket 握手时会在请求头中携带Origin。服务器端有责任检查这个Origin字段并决定是否接受连接。如果服务器不检查那么任何网页都可以尝试连接到你的 WebSocket 服务这可能带来安全风险。服务器端以 Node.js ws 库为例应进行校验const WebSocket require(‘ws‘); const server new WebSocket.Server({ port: 8080 }); server.on(‘connection‘, (socket, request) { const origin request.headers.origin; const allowedOrigins [‘http://localhost:3000‘, ‘https://myapp.com‘]; if (!allowedOrigins.includes(origin)) { socket.close(); // 拒绝非法的源 return; } // 处理合法的连接... });4.3 第三方 API 调用与无后端场景当你需要在前端直接调用无法控制的第三方 API如某些开放平台接口而对方又没有启用 CORS 时你会陷入困境。此时JSONP 是备选如果对方支持但更通用的方案是自建一个简单的后端代理。你可以快速搭建一个 Node.js/Express 服务提供一个自己的 API 端点如/proxy/weather在这个服务内部去调用第三方 API然后将结果返回给前端。这样前端到你的代理服务是同源的跨域问题由你的代理服务解决。这也是“反向代理”思想的一种应用。5. 终极心法跨域问题排查清单当你在开发中遇到跨域错误时不要慌张按照以下清单逐步排查绝大多数问题都能定位。确认错误类型首先看浏览器控制台的完整错误信息。是No ‘Access-Control-Allow-Origin‘ header还是Response to preflight request doesn‘t pass这能帮你快速判断是简单请求被拒还是预检失败。检查请求的 Origin在浏览器开发者工具的 Network 面板中找到出错的请求查看 Request Headers 中的Origin值是什么。确保后端允许的源与此匹配。检查响应头查看出错请求的 Response Headers。是否有Access-Control-Allow-Origin值是否正确如果是预检请求还要检查Access-Control-Allow-Methods和Access-Control-Allow-Headers是否包含了实际请求使用的方法和头部。区分简单请求与预检请求确认你的请求是否触发了预检。检查请求方法、Content-Type和自定义头。核对凭证设置如果请求需要携带 Cookie 或 Authorization 头确保前端Fetch API 设置credentials: ‘include‘Axios 设置withCredentials: true。后端Access-Control-Allow-Origin必须是具体的源非*且设置了Access-Control-Allow-Credentials: true。检查代理配置如果是开发环境确认前端开发服务器的代理配置是否正确目标地址是否可达。对于 WSL 等特殊环境注意localhost的指向问题。检查多层网关生产环境可能经过 Nginx、API 网关、CDN 等多层代理。确保每一层都没有错误地修改或重复设置 CORS 头部导致头部冲突如多个Access-Control-Allow-Origin。后端链路追踪在后端服务日志中确认请求是否真的到达了你的应用代码。有时请求可能在更前面的负载均衡器或防火墙就被拦截了。跨域不是洪水猛兽它是 Web 安全的重要组成部分。作为前端开发者理解其原理掌握 JSONP、CORS、代理这几种核心解决方案并能在不同场景开发/生产、简单/复杂请求、可控/不可控后端下灵活选用或组合使用是必备的技能。从最初的 JSONP 取巧到 CORS 的标准协作再到代理的架构思维解决跨域问题的演进也反映了 Web 开发从简单到复杂、从粗放到规范的发展历程。下次再看到 CORS 错误时希望你能胸有成竹快速定位问题所在。