CORS跨域问题彻底解决：从原理到实战排查指南

Access to fetch at https://api.example.com/users from origin http://localhost:3000 has been blocked by CORS policy: No Access-Control-Allow-Origin header is present on the requested resource. 如果你是个前端工程师这段报错基本刻在DNA里了如果你是个后端大概率也被前端拿着这条报错来敲过门。CORS 全称是 Cross-Origin Resource Sharing中文叫跨域资源共享它不是一个 bug而是浏览器内置的一套安全机制。这篇博文我想把 CORS 跨域问题彻底讲透从浏览器为什么要管这件事到预检请求是怎么握手的再到后端、前端、Nginx 各层有哪些解法最后结合我在 Laravel 里处理 PDF 文件、在火狐浏览器里踩过的坑给你一份可以直接照着排查的作业。无论你是刚入门的前端实习生还是被跨域折磨的后端老手这篇都值得收藏。1. 跨域问题的本质浏览器为什么这么“不讲道理”1.1 同源策略浏览器的安全红线很多刚开始写前后端分离项目的人都会困惑我用 Postman 调接口明明好好的回到浏览器就报 CORS服务器不是已经返回数据了吗问题恰恰出在“服务器已经返回数据了”这件事上。浏览器在发起跨域请求后确实会把请求发出去服务器也确实处理了响应也回到浏览器了但浏览器在把数据交给你的 JavaScript 之前先做了一次安全检查检查响应头里有没有允许当前源读取的凭证。没有就直接拦截并把控制台里的报错甩给你。这个安全机制叫同源策略是浏览器从诞生起就定下的红线。它的核心目的是防止一个网站上的恶意脚本偷偷去读取你在另一个网站上的数据。比如你在网银页面登录了又打开了一个恶意网站如果没有同源策略这个恶意网站里的 JavaScript 就可以向网银接口发请求然后读取响应里的账户信息。这不是危言耸听是真实存在的安全风险。所以浏览器规定只有当请求的“源”和当前页面的“源”一致时JavaScript 才能读取响应内容。1.2 跨域判定协议、域名、端口一个不同就算跨域所谓“源”由三部分组成协议、域名、端口。这三个只要有一个不一样就是跨域。当前页面源目标接口地址是否跨域不一致的地方http://localhost:3000http://localhost:3000/api否无http://localhost:3000http://localhost:3001/api是端口不同http://localhost:3000https://localhost:3000/api是协议不同http://localhost:3000http://api.example.com/api是域名不同http://www.example.comhttp://example.com/api是子域名不同这里要特别提醒一个容易忽略的点localhost 和 127.0.0.1 在很多人的直觉里是同一个地址但对浏览器来说它们代表不同的源。你本地页面跑在 http://localhost:8080接口跑在 http://127.0.0.1:8081照样会被 CORS 拦。类似的还有 example.com 和 www.example.com也是不同源。1.3 不是服务器不给你数据是浏览器拦住了响应很多人对 CORS 有个误区以为是服务器拒绝了请求。实际上请求往往已经到了服务器服务器也正常处理完并且返回了数据。浏览器拿到响应后发现响应头里没有 Access-Control-Allow-Origin或者这个头的值与当前页面的源不匹配于是“替你做主”把响应藏了起来不让 JavaScript 读取。Postman、curl 这类工具没有同源策略所以它们不会报 CORS 错误。这也就解释了一个经典现象后端用 Postman 测接口一切正常前端用浏览器一调就报 “has been blocked by CORS policy”。明白这个底层逻辑之后解决思路就清晰了要么让服务器在响应里带上正确的 CORS 头要么让请求走同源路径前端代理、Nginx 反向代理要么用不支持 CORS 的旧方案JSONP绕开。后面几个小节我会逐个说。2. CORS 到底是怎么工作的2.1 浏览器和服务器之间的“预检”握手CORS 并不是浏览器无脑拦截。对于某些跨域请求浏览器会先发一个请求方式为 OPTIONS 的“预检请求”给服务器问它我要从 example.com 向你的 /api 发一个带 JSON 的 POST 请求你允许这个跨域请求吗允许的话得用响应头告诉我。服务器如果返回了符合要求的 CORS 头浏览器才继续发真正的业务请求如果预检没通过浏览器直接就报错了那个真正的请求根本不会发出去。这就是为什么很多后端在排查跨域问题时会在日志里看到频繁的 OPTIONS 请求甚至觉得是前端在重复请求。实际上那是浏览器在“试探”。预检请求的响应头里主要包含 Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers 等字段相当于服务器对外发布的“跨域白名单”。2.2 几个关键响应头逐一说清楚我在实际联调中见过不少同事手写 CORS 响应头但少写一个就掉坑里。这里把最关键的几个字段列出来Access-Control-Allow-Origin允许哪些源访问。可以写具体的源比如 https://example.com也可以写星号 *表示允许所有源。Access-Control-Allow-Methods允许哪些请求方法比如 GET、POST、PUT、DELETE、OPTIONS。Access-Control-Allow-Headers允许请求里携带哪些自定义头比如 Content-Type、Authorization、X-Requested-With。Access-Control-Allow-Credentials是否允许携带 Cookie。如果设置为 true那么 Access-Control-Allow-Origin 就不能写成 *必须写具体源。Access-Control-Max-Age预检请求的结果能缓存多少秒。设置一个较大的值可以减少浏览器频繁发 OPTIONS 请求对性能有明显帮助。这里有个很常见的坑前端请求里带了 Authorization 头但后端 Access-Control-Allow-Headers 里没有包含 Authorization那么预检就会失败。还有前端请求是带 Cookie 的后端把 Allow-Origin 配成了 *又同时允许了 Allow-Credentials: true这本身就违反了规范浏览器同样会拦截。2.3 简单请求和预检请求哪些场景会触发预检CORS 把跨域请求分成两类简单请求和预检请求。简单请求不会触发 OPTIONS 预检浏览器直接发送真实请求然后检查响应头。简单请求必须同时满足以下条件请求方法只能是 GET、HEAD、POST 之一。除了浏览器自动设置的头部之外只能手动设置 Accept、Accept-Language、Content-Language、Content-Type 这几个头。如果 Content-Type 有值只能是 application/x-www-form-urlencoded、multipart/form-data、text/plain 之一。请求不能使用 ReadableStream 对象。也就是说如果前端要用 application/json 传 POST 请求或者要带 Authorization 头这就不是简单请求了浏览器会先发一个 OPTIONS 预检请求。这也是为什么很多接口用 GET 没事一改 POST 就报 CORS 的原因。理解这一点对于后面的配置和排查至关重要。3. 最常用的解决手段后端为主前端也有招3.1 手写中间件最底层的 CORS 响应头设置不管用什么语言、什么框架CORS 的底层解决逻辑都差不多在处理请求的中间件或过滤器里往响应头里添加相应的 Access-Control-* 字段。以 Node.js 原生 HTTP 为例const http require(http); http.createServer((req, res) { res.setHeader(Access-Control-Allow-Origin, *); res.setHeader(Access-Control-Allow-Methods, GET, POST, PUT, DELETE, OPTIONS); res.setHeader(Access-Control-Allow-Headers, Content-Type, Authorization); if (req.method OPTIONS) { res.writeHead(204); res.end(); return; } // 正常业务处理 res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ message: hello })); }).listen(3000);这里有个细节当收到 OPTIONS 预检请求时最好直接返回 204 并结束请求不要再继续走业务逻辑。因为预检请求本身不带业务数据服务器只需要回 CORS 头即可。如果不做这个判断有些框架会在 OPTIONS 请求上误报路由不存在导致预检失败。3.2 框架内置方案Express、Spring Boot、Laravel 怎么配用框架开发时通常不需要自己手写中间件框架都提供了成熟方案。Express 生态里最常用的是 cors 中间件const express require(express); const cors require(cors); const app express(); app.use(cors({ origin: [http://localhost:3000, https://example.com], methods: [GET, POST, PUT, DELETE], allowedHeaders: [Content-Type, Authorization], credentials: true, maxAge: 86400 })); app.get(/api/users, (req, res) { res.json({ users: [] }); }); app.listen(3000);Spring Boot 里最简洁的做法是写一个配置类Configuration public class CorsConfig { Bean public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurer() { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(http://localhost:3000) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(Content-Type, Authorization) .allowCredentials(true) .maxAge(3600); } }; } }Laravel 从 9 开始官方把 CORS 支持整合进了框架的 config/cors.php 配置文件。你可以在这里定义允许的路径、源、方法和头。如果你用的是 Laravel 8通常会依赖 fruitcake/laravel-cors 这个包配置方式也类似。3.3 Laravel 中 Storage 里 PDF 文件的跨域错误怎么处理热搜词里有个很典型的场景Laravel storage pdf cors 错误。我实际遇到的情况是项目里把 PDF 上传到了 storage/app/private 下然后通过一个后端路由去读取文件并输出到浏览器。前端项目跑在另一个端口直接用 标签或 window.open 去访问这个 PDF 地址结果控制台报 CORS 错误。这里有两个层面的问题要区分。如果 PDF 放在 Laravel 的 public 目录或者通过 storage:link 链接到 public/storage 目录而服务器也没做特殊拦截那么浏览器直接访问静态文件时文件通常是由 Nginx 或 Apache 返回的不经过 Laravel 中间件自然也就没有 CORS 头。解决办法也很直接在 Nginx 或 Apache 层给这些静态文件目录加 CORS 头或者在访问 PDF 的路由里手动添加响应头。如果是通过 Laravel 路由来读取 storage 里的文件比如Route::get(/docs/{file}, function ($file) { $path storage_path(app/private/ . $file); if (!file_exists($path)) { abort(404); } return response()-file($path, [ Access-Control-Allow-Origin *, Content-Type application/pdf, ]); });要注意 response()-file 是往响应头里附加自定义头的正确方式。同时如果你的 Laravel 版本带有全局 CORS 中间件而且这个路由也在 config/cors.php 的 paths 范围内那其实不用手动加。但问题就在于很多项目的 config/cors.php 里 paths 默认只配置了 api/*不包含这个自定义 PDF 路由所以才会被拦截。我建议的做法是把需要跨域的 PDF 路由路径也加到 config/cors.php 的 paths 数组里让框架统一处理而不是在业务代码里到处加头维护成本低也不容易漏。具体来说先确认内核里已经注册了 HandleCors 中间件然后修改 config/cors.php比如paths [api/*, docs/*],这样访问 /docs/xxx.pdf 时Laravel 就会自动返回 CORS 头了。3.4 前端开发环境代理Vite / webpack-dev-server 怎么绕过前端本地开发时最常见的做法不是去改后端而是把请求代理到同源路径。开发服务器本身是 Node.js 服务可以接收浏览器的请求再转发给后端的真实地址。由于浏览器只认页面所在的源它看到的请求是同源的就不存在跨域问题了。Vite 的配置在 vite.config.js 里export default { server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } }配置完之后前端代码里请求 /api/users开发服务器会把请求转发到 http://localhost:8080/users同时保持响应经过代理转发。对浏览器来说页面和请求都在 localhost:5173Vite 默认端口完全同源。webpack-dev-server 的配置逻辑类似module.exports { devServer: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: } } } } }这里有个细节changeOrigin 要设为 true否则后端拿到的 Host 头还是前端开发服务器的地址有些后端会校验 Host导致请求异常。另外代理只能解决开发环境的跨域生产环境如果前后端部署在不同的源还是得靠后端 CORS 或 Nginx。3.5 生产环境用 Nginx 反向代理生产环境里最干净的做法是让前端和后端共用同一个域名通过 Nginx 把不同路径转发到不同服务。这样浏览器侧的源完全一致根本触发不了 CORS。比如前端部署在 https://example.com后端 API 在 https://api.example.com可以在 Nginx 里把 /api 前缀的请求反向代理到后端的真实地址。一个常见的配置片段server { listen 443 ssl; server_name example.com; location / { root /var/www/frontend; try_files $uri /index.html; } location /api/ { proxy_pass http://localhost:8080; 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; } }前端页面里的接口请求都写成相对路径 /api/xxx这样浏览器访问的是 https://example.com/api/xxx与页面同源。Nginx 再把请求转发到后端服务整个过程由服务端完成浏览器感知不到跨域自然不会有 CORS 拦截。这种方案不仅解决了跨域还顺带降低了前后端分离下 Cookie 传递的复杂性我个人非常推荐。3.6 临时方案JSONP、关闭浏览器安全策略、浏览器扩展有些场景下你没法改后端也没法动 Nginx就会有人想到 JSONP。JSONP 的原理是利用