前后端分离几乎是Vue项目的标配而一旦上了前后端分离跨域请求这关基本绕不过去。用Vue配ThinkPHP做接口开发的场景太常见了但很多新手甚至做了两三年的同学在跨域这个问题上仍然是一头雾水前端明明开了代理请求却还是报错后端明明加了header浏览器照样给你CORS error。这篇文章我从两端都讲透把开发环境、生产环境、预检请求、携带Cookie这些实际开发中会碰到的坑全部过一遍所有配置都是可以在项目里直接落地的方案。先说清楚本文解决的核心问题Vue前端工程在请求ThinkPHP后端接口时如何正确配置跨域让请求在开发环境、测试环境、生产环境都能稳定跑通。适合正在用Vue ThinkPHP做前后端分离项目、被跨域问题卡住、或者想系统搞明白CORS原理顺手把配置理顺的同学。1. 跨域问题是怎么产生的ThinkPHP和Vue各自要承担什么1.1 浏览器同源策略才是罪魁祸首跨域这个词被说烂了但每次排查问题的时候还是有人分不清为什么我的接口用Postman能通放到浏览器就报错。核心原因就一句话浏览器的同源策略在管着你Postman不是浏览器它不管这个。同源策略要求页面请求接口时协议、域名、端口三个必须完全一致任何一个不同浏览器就会拦截响应。比如你的Vue开发服务器跑在http://localhost:8080ThinkPHP接口跑在http://localhost:80端口不一样这就是跨域。再比如前端用域名www.a.com后端用api.a.com二级域名不一样同样跨域。所以跨域不是你后端接口有问题也不是你前端代码有问题而是浏览器这层安全检查机制在保护你。理解了这一层后面所有配置就都好懂了——我们做的所有事情本质上都是为了让浏览器愿意把响应交给页面。1.2 开发环境和生产环境的跨域思路是不同的这是整个Vue ThinkPHP项目里最容易搞混的地方。很多人把开发环境用的Vite代理配置直接想当然地套到生产环境发现根本不生效然后开始怀疑人生。开发环境下前端跑在Node服务上Vite或者webpack-dev-server后端跑在独立域名或端口上。此时最干净的做法是用代理。原理很简单浏览器是同源策略管着的但Node服务端发请求没有这个限制于是我们让前端页面请求一个同源的地址由Node服务端把这个请求转发到真正的接口地址再拿Response回来给浏览器。浏览器全程不知道发生过转发它看到的只是同源请求自然不报跨域错误。生产环境下Vue打包后是纯静态文件没有Node服务帮你转发。这时候要么让Nginx做一层反向代理要么就得靠后端配合在响应头里明确告诉浏览器我有资格跨域访问。而ThinkPHP此时就要承担起设置CORS响应头的责任。所以实操中我推荐这样分工开发环境用Vite代理生产环境用Nginx代理为主、后端CORS兜底。很多团队生产环境其实也需要后端开CORS因为在某些场景下前端静态文件和API就是分布在不同的域名上这就要后端真正处理跨域。1.3 CORS机制的关键点预检请求CORS跨域资源共享是W3C的标准核心就是通过HTTP响应头告诉浏览器要不要放行。要搞明白CORS配置必须知道一个概念——预检请求Preflight。当你的请求满足以下任一条件时浏览器会先发一个OPTIONS请求探路这就是预检使用非GET/POST方法比如PUT、DELETEPOST请求的Content-Type不是application/x-www-form-urlencoded、multipart/form-data或text/plain请求头里带了自定义头部比如Authorization、X-Token预检请求发出去之后浏览器会看响应头里有没有对应的Access-Control-Allow-*。没有、或者字段不对浏览器就直接拦截控制台报CORS error你的业务请求压根不会真正发出去。ThinkPHP后端配置跨域的核心工作就是处理响应头以及正确回应预检请求。很多后端同学只加了Access-Control-Allow-Origin但没处理OPTIONS前端一用自定义header就挂了原因就在这。2. ThinkPHP端跨域配置三种方案我都验证过2.1 方案一ThinkPHP6中间件全局配置推荐ThinkPHP6是基于中间件架构的这是最优雅、最干净的方案。直接在中间件里统一处理响应头所有接口都能生效不需要每个控制器去写重复代码。首先创建一个中间件在app/middleware.php里注册全局生效。中间件代码我直接贴出来这是我项目里一直在用的版本?php declare(strict_types1); namespace app\middleware; use Closure; use think\Request; use think\Response; class CorsMiddleware { public function handle(Request $request, Closure $next) { $origin $request-header(origin, *); $header [ Access-Control-Allow-Origin $origin, Access-Control-Allow-Credentials true, Access-Control-Allow-Methods GET, POST, PUT, DELETE, PATCH, OPTIONS, Access-Control-Allow-Headers Authorization, Content-Type, X-Token, Accept, Origin, X-Requested-With, Access-Control-Max-Age 86400, ]; if ($request-method() OPTIONS) { return Response::create(, html, 204)-header($header); } $response $next($request); $response-header($header); return $response; } }然后在app/middleware.php里注册?php // 全局中间件定义文件 return [ \app\middleware\CorsMiddleware::class, ];这里有几个细节要注意。第一Access-Control-Allow-Origin我这里是动态取浏览器传来的Origin。为什么不能用*因为Access-Control-Allow-Credentials: true和*不能同时出现。只要你想让跨域请求携带Cookie后面会讲Origin就必须明确指定不能用通配符。第二OPTIONS请求必须返回204状态码而不是200。这是很多人容易忽略的。浏览器预检请求只关心响应头不关心业务数据204是最省资源的处理方式。如果你返回200有些浏览器也能过但严格来说204才是标准做法。第三Access-Control-Allow-Headers要尽量齐全因为你不知道前端axios拦截器里加了什么自定义头。常见的Authorization、Content-Type必须带上。如果你用的token名比较特殊比如X-Token或者X-Access-Token也要在这里面加进去否则前端每次带token请求都会被拦截。2.2 方案二在公共文件或入口文件直接设置header有些老项目还在用ThinkPHP5或者不想动中间件结构那可以直接在public/index.php入口文件里加header或者在某个公共控制器基类里统一设置。入口方式最粗暴header(Access-Control-Allow-Origin: *); header(Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Authorization, Content-Type, X-Token); if ($_SERVER[REQUEST_METHOD] OPTIONS) { http_response_code(204); exit; }放到public/index.php的最前面任何请求进来都会先经过这些header设置。这个方案适合快速验证、临时解决但不适合正式项目使用因为控制器里不好动态判断跨域来源Cookie场景下没法精确控制Origin。如果你用的是ThinkPHP5.1也可以在application下建一个公共控制器比如BaseController在_initialize方法里统一设置响应头所有控制器继承它。public function _initialize() { header(Access-Control-Allow-Origin: . $_SERVER[HTTP_ORIGIN] ?? *); header(Access-Control-Allow-Credentials: true); header(Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Authorization, Content-Type, X-Token); if ($_SERVER[REQUEST_METHOD] OPTIONS) { exit(); } }这两种方式本质一样原理都是赶在业务逻辑执行前设置响应头并拦截掉预检请求。缺点是不够灵活、代码侵入性强适合没有中间件机制的老版本。2.3 方案三路由级跨域控制还有一种场景比如你只希望某个接口允许跨域而不是全部接口。这时候不需要全局中间件直接在路由定义时加中间件或者单独处理即可。ThinkPHP6路由支持中间件绑定Route::group(api, function () { Route::post(login, Login/index); Route::post(userinfo, User/info); })-middleware(\app\middleware\CorsMiddleware::class);这样只有/api前缀下的接口会走CORS中间件其他的路由不受影响。对于某些只给特定端调用的接口比如开放平台API这种精细控制的方案就会很好用。2.4 别忘了框架异常响应也要跨域这是ThinkPHP配置跨域时最容易踩的暗坑。你中间件倒是配好了普通请求都能过但一旦接口报错——参数验证失败、SQL异常、自定义异常抛出——框架返回的JSON错误提示没有经过中间件的header设置浏览器照样拦你。为什么因为中间件是在正常请求链路里执行的但框架捕获异常后会走独立的异常处理流程直接返回Response跳过了正常的中间件管道。解决办法是在异常处理类里也加上CORS头。在app/ExceptionHandle.php里重写render方法public function render($request, Throwable $e): Response { $response parent::render($request, $e); $response-header([ Access-Control-Allow-Origin $request-header(origin, *), Access-Control-Allow-Credentials true, Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS, Access-Control-Allow-Headers Authorization, Content-Type, X-Token, ]); return $response; }这个细节如果你不处理会出现一个特别迷惑的现象接口在Postman里测试好好的浏览器里业务正常请求也没问题但一旦某个请求触发了参数校验错误浏览器就报CORS error然后你开始怀疑是不是参数传错了最后排查半天发现是异常响应的跨域头丢了。3. Vue端配置Vite代理和axios必须配合好3.1 Vite代理配置详解现在Vue3项目基本都是Vite构建了Vite的代理配置写在vite.config.js里。我直接说最常用的配置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 3000, host: true, proxy: { /api: { target: http://localhost:80, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } })这个配置的含义是前端所有以/api开头的请求Vite开发服务器会转发到http://localhost:80同时把路径里的/api前缀去掉。这里解释几个关键项有同学照抄了配置但不知道含义出了问题就不知道怎么调。target是后端接口的真实地址。如果你的ThinkPHP运行在小皮面板上端口是80那就填http://localhost:80。如果用的是php think run命令那就是http://localhost:8000。这个地址决定了你的请求往哪里转发。changeOrigin必须设为true。这个参数的作用是修改请求头里的Host字段为目标域名。你的页面跑在localhost:3000直接向后端转发时Host是localhost:3000如果ThinkPHP那边做了域名校验或者二级域名解析就会被拒绝。设为true后Host会变成localhost:80后端感觉就像在直接服务这个请求。rewrite是否启用要看后端路由规则。如果ThinkPHP的路由里没有/api前缀那必须把/api重写掉如果你后端所有控制器都挂在/api路由组下那就不需要这行。有个细节特别容易坑到人server.proxy只在开发环境生效打包之后你部署到Nginx上这个配置直接被无视。所以千万别指望前端配置能解决生产环境的跨域。3.2 vue-cli项目的proxy配置如果你还在维护老项目用的是vue-cliwebpack配置在vue.config.js里module.exports { devServer: { port: 3000, proxy: { /api: { target: http://localhost:80, changeOrigin: true, pathRewrite: { ^/api: } } } } }逻辑和Vite的proxy几乎一样只是字段名从rewrite变成了pathRewrite。要注意的是改完vue.config.js必须重启devServerwebpack不会热加载这个配置文件我记得这一点经常有人不知道改完刷新页面发现配置没生效狂刷新浏览器其实重启一下服务就好了。3.3 axios的baseURL和拦截器配置代理配好了前端请求也不能随便发。如果axios的baseURL或者请求路径写死了后端地址代理就形同虚设。举个反例// 错的做法绕过了代理直接请求后端地址 axios.get(http://localhost:80/api/user/info)这样做代理根本不拦截浏览器直接发请求到localhost:80跨域错误照旧。正确做法是统一走代理前缀// axios实例 const service axios.create({ baseURL: /api, timeout: 15000 }) // 请求拦截器 service.interceptors.request.use( config { const token localStorage.getItem(token) if (token) { config.headers[Authorization] Bearer token config.headers[X-Token] token } return config }, error Promise.reject(error) ) // 响应拦截器 service.interceptors.response.use( response { const res response.data if (res.code ! 200) { // 业务错误处理 return Promise.reject(new Error(res.msg)) } return res }, error { if (error.response error.response.status 401) { // 登录态失效处理 } return Promise.reject(error) } ) export default service注意这里baseURL的值是/api配合Vite代理配置实际上请求会被转发到http://localhost:80并把/api去掉。如果你的代理配置里没有rewrite那其实是把请求转发到http://localhost:80/api/...那ThinkPHP后台就需要在路由组/api下面处理。所以Vite端的rewrite和ThinkPHP路由规则必须前后对得上不然就会出现404。3.4 代理配好之后怎么确认请求真的走了代理这问题对应到一个热词vue配置跨域代理后如何获取我的真实的请求地址。排查这个问题的场景经常是接口通了但后端日志里看到的访问路径不对或者前端想确认代理到底重写成了什么。最直接的办法是看浏览器Network面板。打开开发者工具切到Network点击你要排查的请求。看Request URL如果代理生效它显示的是http://localhost:3000/api/user/info这种前端同源地址不会直接显示后端地址。但Network里显示的地址只是前端发出的地址不是被代理转发后的真实后端地址。要去后端确认最可靠的是看ThinkPHP的日志。TP6的日志默认在runtime/log/目录下里面会记录每一条请求的完整URL、请求方法、请求时间。如果代理配置了rewrite日志里显示的路径就不带/api前缀。另外还可以在Vite配置里临时加一个configure回调proxy: { /api: { target: http://localhost:80, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ), configure: (proxy) { proxy.on(proxyReq, (proxyReq, req, res) { console.log(代理转发请求: , req.url, - , proxyReq.path) }) } } }proxyReq事件会在代理转发请求时触发控制台会打印转发的目标路径。排查看不到真实请求地址的问题时这一招比什么方法都好使。4. 生产环境部署去掉Vite代理后跨域就这么处理4.1 Nginx反向代理配置项目上线后没有Vite帮你转发请求了。最常见的部署方案是把Vue打包后的dist目录丢到Nginx然后让Nginx在同一份配置里既跑前端静态资源又代理API请求到ThinkPHP。假设你的域名是www.example.comVue静态文件在/var/www/distThinkPHP接口运行在http://127.0.0.1:80或者另一台服务器http://backend-server。Nginx配置可以这样写server { listen 80; server_name www.example.com; # Vue静态资源 root /var/www/dist; index index.html; # 前端路由history模式必须加 location / { try_files $uri $uri/ /index.html; } # API反向代理 location /api/ { proxy_pass http://127.0.0.1:80/; 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; } }关键在于location /api/块。proxy_pass http://127.0.0.1:80/;末尾带了一个/这表示把URL里匹配的/api/前缀去掉后再转发。比如请求的是/api/user/info代理转发给后端的实际路径是/user/info。这跟Vite的rewrite是同一个逻辑。如果你希望后端保留/api前缀把proxy_pass改成http://127.0.0.1:80;即可末尾不带/。具体用哪种依然取决于你ThinkPHP的路由定义。这里还要注意一个坑如果Vue路由用了history模式没有#号那种URL必须在location /里配置try_files $uri $uri/ /index.html;否则用户直接访问www.example.com/user/center这种前端路由时Nginx会找服务器的真实文件找不到就返回404。这是Vue部署最常见的坑之一很多同学问为什么Vue打包装好后刷新就404就是这行配置没写。4.2 没有Nginx代理时的纯CORS方案有些情况没办法用Nginx转发比如Vue静态文件托管在CDN或者对象存储上API在独立服务器前端页面和接口完全不在同一个域下。这时候就必须靠后端CORS来解决。实际上ThinkPHP后端的CORS中间件在生产环境同样生效。只要你在Nginx里没有代理、直接请求接口域名时后端返回的响应头里带上了Access-Control-Allow-*浏览器就会放行。但纯CORS方案有个体验问题——请求会分成两步先OPTIONS预检再正式请求网络请求量翻倍。所以如果条件允许我还是建议用Nginx代理至少在生产环境里代理是成本最低、速度最快的方案。4.3 打包后布局异常的排查思路热词里有一条vue 打包后 布局异常我顺手讲一下因为这个问题经常和跨域配置同时出现在部署阶段很多人会以为是跨域导致的。Vue打包后布局异常90%以上是静态资源路径问题。默认情况下Vite打包的资源路径是绝对路径/assets/xxx如果你的前端文件不是部署在域名根目录而是部署在www.example.com/project/这种子目录下绝对路径就找不到资源文件于是页面CSS全部加载失败看起来就是布局崩了。解决办法是在vite.config.js里设置baseexport default defineConfig({ base: ./, // 使用相对路径 plugins: [vue()] })设置成./后打包后的资源引用会变成相对路径无论把dist部署到哪个子目录下都能正常加载。如果部署在Nginx子目录同时还要在Nginx location里配置try_files时带上子目录前缀这里不是跨域问题我就不展开说了。5. 踩坑实录跨域请求的常见问题与排查技巧5.1 问题配置完还是报CORS error我见过太多人卡在这一步后端header加了前端proxy也配了结果还是报Access-Control-Allow-Origin错误。这时候先不要改代码按这个顺序排查第一步打开浏览器的Network面板看报错的请求。区分一下它是OPTIONS还是实际的GET/POST请求。如果是OPTIONS挂了问题几乎一定在后端预检处理上重点检查后端是否拦截了OPTIONS、是否返回204。如果是GET/POST挂了重点看浏览器的Console报错信息它会告诉你是少了Access-Control-Allow-Origin还是Access-Control-Allow-Headers。第二步确认前端请求到底有没有走代理。如果Network面板里请求URL显示的是http://localhost:80/api/xxx说明代理没生效axios的baseURL被写死成后端地址了。如果显示的是http://localhost:3000/api/xxx说明代理在拦截。第三步检查后端日志确认请求有没有真正到达ThinkPHP。如果TP日志里压根没有这条请求记录说明请求在代理层就被拦截了这时候要检查Vite的target地址能不能通。5.2 问题跨域Cookie带不上登录态保存不了跨域请求默认是不携带Cookie的。如果你前后端分离但登录态存在Cookie里你会遇到一个诡异的现象登录接口返回成功Set-Cookie也发了但浏览器就是不存导致后续请求全部401。要解决必须同时满足三个条件前端axios请求设置withCredentials: true或fetch的credentials: include后端Access-Control-Allow-Origin不能是*必须是具体的域名后端Access-Control-Allow-Credentials必须为trueaxios实例创建时加上const service axios.create({ baseURL: /api, timeout: 15000, withCredentials: true })或者使用默认配置axios.defaults.withCredentials true如果你的项目登录态是用TokenlocalStorage存储而不是Cookie那这个坑可以完美避开。个人建议能走Token就不要走跨域Cookie省一大串麻烦。5.3 问题带了自定义Header的请求全被浏览器拦截这个问题很典型。前端在拦截器里加了config.headers[X-Token] token去传用户凭证结果发现所有带这个Header的请求都会被浏览器拦截报错信息里明确写着Request header field x-token is not allowed by Access-Control-Allow-Headers in preflight response.原因就是后端Access-Control-Allow-Headers没把X-Token加进去。有些同学只写了Authorization, Content-Type前端实际用的是X-Token自然被拦。解决方式很简单把后端允许的Headers列表补全Access-Control-Allow-Headers Authorization, Content-Type, X-Token, X-Requested-With, Accept, Origin,如果你嫌麻烦想通配所有自定义头理论上可以写*但要注意它和Allow-Credentials: true的兼容性问题稳妥起见还是把用到的Header名都列出来反正也就是多写几个字母的事。5.4 问题ThinkPHP开启了二级域名设置后跨域失效有同学项目用上了二级域名比如主站是www.example.com接口所在的模块绑定到api.example.com这时跨域问题会变得比较微妙。首先明确一点www.example.com和api.example.com之间本身就是跨域的因为它们域名不同。即使你通过Nginx把两个域名的请求都转发到同一个ThinkPHP应用浏览器依然会视为跨域请求。其次ThinkPHP的域名绑定是在路由层面处理的跨域配置依然要依赖刚才说的中间件方案。如果配置了域名绑定后跨域失效先检查是不是绑定的域名不在后端允许的Origin列表里。比如中间件里写死了Access-Control-Allow-Origin http://localhost:3000,生产环境换成https://www.example.com如果前端实际域是https://api.example.com调你接口那也会被拦。最稳妥的做法是做一个动态白名单允许你控制的域名都通过$allowedOrigins [ https://www.example.com, https://admin.example.com, http://localhost:3000, ]; $origin $request-header(origin, ); if (in_array($origin, $allowedOrigins)) { $header[Access-Control-Allow-Origin] $origin; }5.5 问题OPTIONS请求在ThinkPHP里返回405有同学后端配置了路由但OPTIONS请求到后端返回的是405 Method Not Allowed。原因也简单——TP路由默认只允许你定义的路由方法和请求方法匹配你定义了Route::post()那OPTIONS请求自然匹配不到加上TP的405异常又提前返回了于是预检请求直接失败。解决方案还是CORS中间件那套因为中间件是在路由匹配之前执行能拦截掉OPTIONS请求直接返回204不进入路由解析阶段。就是这个顺序问题导致很多人在控制器层处理OPTIONS事倍功半。5.6 问题代理配置不生效的检查清单如果你的Vite代理配好了但就是不生效按这个清单逐项排查第一确认Vite服务重启了。修改vite.config.js之后devServer必须重启才生效。有很多同学改完配置只是刷新页面配置压根没有重新加载。第二确认前端发请求时用的是相对路径/api/xxx而不是绝对URLhttp://xxx.com/api。绝对URL不会走代理。第三确认代理键名和请求前缀一致。如果你配置的是/api但前端请求路径是/api/v1/user/info代理是能匹配上的如果你前端请求的是/user/info没有/api前缀代理配置就完全没用。第四确认target地址在后端服务器能正常访问。直接在浏览器打开http://localhost:80看看是不是能访问ThinkPHP的入口页。如果连后端服务都没启动代理转发了也是白搭。5.7 附跨域配置排查速查表现象可能原因排查重点OPTIONS请求报CORS错误后端未处理预检请求或返回状态码不对后端中间件是否拦截OPTIONS并返回204实际业务请求报CORS错误Allow-Origin缺失或headers列表不全后端响应头字段是否正确带了自定义header就报错Allow-Headers缺少对应字段前端自定义Header名是否在后端白名单里请求没走代理直接请求后端axios baseURL写死绝对地址前端请求地址是否以/api开头且相对路径Cookie跨域丢失前端没开withCredentials或后端Origin不是具体域名三条件是否同时满足异常响应也报CORS异常处理类里没加跨域头ExceptionHandle的render方法移动端/小程序直接请求接口跨域策略不适用于非浏览器环境确认环境类型非浏览器可绕过CORS机制6. 最后分享一个小技巧把跨域配置做成一个可复用的模板在多个项目间跳来跳去的时候会发现跨域配置的代码几乎是一样的。我自己是维护了一套可以直接复用的模板新项目拿到了先丢进去能省不少时间。ThinkPHP端的中间件文件我存档了一份放在项目的app/middleware/目录下同时把异常处理类的跨域头也写进了自己的代码片段库。Vite端的代理配置、Nginx的跨域配置也都有模板。不过模板只是第一步每次接入还是要看具体项目的实际情况。比如有的项目需要携带CookieOrigin不能写*有的项目只做公众号网页调用允许的域名就一个有的项目前后端不同域名部署走的就是CORS有的项目同一域名下用Nginx代理后端甚至不需要开CORS。另外多说一句跨域配置涉及前端、后端、运维三层团队协作时最好在接口文档里把跨域约定写清楚后端允许的Headers列表是什么、前端请求是否携带Cookie、生产环境走Nginx代理还是后端CORS。让每个人都知道自己在整个链路里负责哪一环排查问题时不会互相甩锅。我在实际项目里感受到最深的体会是跨域问题看着是配置问题本质上是前端不知道后端怎么接收、后端不知道前端怎么请求的沟通问题。两边各管一摊谁也不清楚对方的链路出了错就只能对着Network面板干瞪眼。把链路捋清楚把每一层的配置都验证过一遍跨域真的只是三分钟的事。
前后端分离几乎是Vue项目的标配而一旦上了前后端分离跨域请求这关基本绕不过去。用Vue配ThinkPHP做接口开发的场景太常见了但很多新手甚至做了两三年的同学在跨域这个问题上仍然是一头雾水前端明明开了代理请求却还是报错后端明明加了header浏览器照样给你CORS error。这篇文章我从两端都讲透把开发环境、生产环境、预检请求、携带Cookie这些实际开发中会碰到的坑全部过一遍所有配置都是可以在项目里直接落地的方案。先说清楚本文解决的核心问题Vue前端工程在请求ThinkPHP后端接口时如何正确配置跨域让请求在开发环境、测试环境、生产环境都能稳定跑通。适合正在用Vue ThinkPHP做前后端分离项目、被跨域问题卡住、或者想系统搞明白CORS原理顺手把配置理顺的同学。1. 跨域问题是怎么产生的ThinkPHP和Vue各自要承担什么1.1 浏览器同源策略才是罪魁祸首跨域这个词被说烂了但每次排查问题的时候还是有人分不清为什么我的接口用Postman能通放到浏览器就报错。核心原因就一句话浏览器的同源策略在管着你Postman不是浏览器它不管这个。同源策略要求页面请求接口时协议、域名、端口三个必须完全一致任何一个不同浏览器就会拦截响应。比如你的Vue开发服务器跑在http://localhost:8080ThinkPHP接口跑在http://localhost:80端口不一样这就是跨域。再比如前端用域名www.a.com后端用api.a.com二级域名不一样同样跨域。所以跨域不是你后端接口有问题也不是你前端代码有问题而是浏览器这层安全检查机制在保护你。理解了这一层后面所有配置就都好懂了——我们做的所有事情本质上都是为了让浏览器愿意把响应交给页面。1.2 开发环境和生产环境的跨域思路是不同的这是整个Vue ThinkPHP项目里最容易搞混的地方。很多人把开发环境用的Vite代理配置直接想当然地套到生产环境发现根本不生效然后开始怀疑人生。开发环境下前端跑在Node服务上Vite或者webpack-dev-server后端跑在独立域名或端口上。此时最干净的做法是用代理。原理很简单浏览器是同源策略管着的但Node服务端发请求没有这个限制于是我们让前端页面请求一个同源的地址由Node服务端把这个请求转发到真正的接口地址再拿Response回来给浏览器。浏览器全程不知道发生过转发它看到的只是同源请求自然不报跨域错误。生产环境下Vue打包后是纯静态文件没有Node服务帮你转发。这时候要么让Nginx做一层反向代理要么就得靠后端配合在响应头里明确告诉浏览器我有资格跨域访问。而ThinkPHP此时就要承担起设置CORS响应头的责任。所以实操中我推荐这样分工开发环境用Vite代理生产环境用Nginx代理为主、后端CORS兜底。很多团队生产环境其实也需要后端开CORS因为在某些场景下前端静态文件和API就是分布在不同的域名上这就要后端真正处理跨域。1.3 CORS机制的关键点预检请求CORS跨域资源共享是W3C的标准核心就是通过HTTP响应头告诉浏览器要不要放行。要搞明白CORS配置必须知道一个概念——预检请求Preflight。当你的请求满足以下任一条件时浏览器会先发一个OPTIONS请求探路这就是预检使用非GET/POST方法比如PUT、DELETEPOST请求的Content-Type不是application/x-www-form-urlencoded、multipart/form-data或text/plain请求头里带了自定义头部比如Authorization、X-Token预检请求发出去之后浏览器会看响应头里有没有对应的Access-Control-Allow-*。没有、或者字段不对浏览器就直接拦截控制台报CORS error你的业务请求压根不会真正发出去。ThinkPHP后端配置跨域的核心工作就是处理响应头以及正确回应预检请求。很多后端同学只加了Access-Control-Allow-Origin但没处理OPTIONS前端一用自定义header就挂了原因就在这。2. ThinkPHP端跨域配置三种方案我都验证过2.1 方案一ThinkPHP6中间件全局配置推荐ThinkPHP6是基于中间件架构的这是最优雅、最干净的方案。直接在中间件里统一处理响应头所有接口都能生效不需要每个控制器去写重复代码。首先创建一个中间件在app/middleware.php里注册全局生效。中间件代码我直接贴出来这是我项目里一直在用的版本?php declare(strict_types1); namespace app\middleware; use Closure; use think\Request; use think\Response; class CorsMiddleware { public function handle(Request $request, Closure $next) { $origin $request-header(origin, *); $header [ Access-Control-Allow-Origin $origin, Access-Control-Allow-Credentials true, Access-Control-Allow-Methods GET, POST, PUT, DELETE, PATCH, OPTIONS, Access-Control-Allow-Headers Authorization, Content-Type, X-Token, Accept, Origin, X-Requested-With, Access-Control-Max-Age 86400, ]; if ($request-method() OPTIONS) { return Response::create(, html, 204)-header($header); } $response $next($request); $response-header($header); return $response; } }然后在app/middleware.php里注册?php // 全局中间件定义文件 return [ \app\middleware\CorsMiddleware::class, ];这里有几个细节要注意。第一Access-Control-Allow-Origin我这里是动态取浏览器传来的Origin。为什么不能用*因为Access-Control-Allow-Credentials: true和*不能同时出现。只要你想让跨域请求携带Cookie后面会讲Origin就必须明确指定不能用通配符。第二OPTIONS请求必须返回204状态码而不是200。这是很多人容易忽略的。浏览器预检请求只关心响应头不关心业务数据204是最省资源的处理方式。如果你返回200有些浏览器也能过但严格来说204才是标准做法。第三Access-Control-Allow-Headers要尽量齐全因为你不知道前端axios拦截器里加了什么自定义头。常见的Authorization、Content-Type必须带上。如果你用的token名比较特殊比如X-Token或者X-Access-Token也要在这里面加进去否则前端每次带token请求都会被拦截。2.2 方案二在公共文件或入口文件直接设置header有些老项目还在用ThinkPHP5或者不想动中间件结构那可以直接在public/index.php入口文件里加header或者在某个公共控制器基类里统一设置。入口方式最粗暴header(Access-Control-Allow-Origin: *); header(Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Authorization, Content-Type, X-Token); if ($_SERVER[REQUEST_METHOD] OPTIONS) { http_response_code(204); exit; }放到public/index.php的最前面任何请求进来都会先经过这些header设置。这个方案适合快速验证、临时解决但不适合正式项目使用因为控制器里不好动态判断跨域来源Cookie场景下没法精确控制Origin。如果你用的是ThinkPHP5.1也可以在application下建一个公共控制器比如BaseController在_initialize方法里统一设置响应头所有控制器继承它。public function _initialize() { header(Access-Control-Allow-Origin: . $_SERVER[HTTP_ORIGIN] ?? *); header(Access-Control-Allow-Credentials: true); header(Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS); header(Access-Control-Allow-Headers: Authorization, Content-Type, X-Token); if ($_SERVER[REQUEST_METHOD] OPTIONS) { exit(); } }这两种方式本质一样原理都是赶在业务逻辑执行前设置响应头并拦截掉预检请求。缺点是不够灵活、代码侵入性强适合没有中间件机制的老版本。2.3 方案三路由级跨域控制还有一种场景比如你只希望某个接口允许跨域而不是全部接口。这时候不需要全局中间件直接在路由定义时加中间件或者单独处理即可。ThinkPHP6路由支持中间件绑定Route::group(api, function () { Route::post(login, Login/index); Route::post(userinfo, User/info); })-middleware(\app\middleware\CorsMiddleware::class);这样只有/api前缀下的接口会走CORS中间件其他的路由不受影响。对于某些只给特定端调用的接口比如开放平台API这种精细控制的方案就会很好用。2.4 别忘了框架异常响应也要跨域这是ThinkPHP配置跨域时最容易踩的暗坑。你中间件倒是配好了普通请求都能过但一旦接口报错——参数验证失败、SQL异常、自定义异常抛出——框架返回的JSON错误提示没有经过中间件的header设置浏览器照样拦你。为什么因为中间件是在正常请求链路里执行的但框架捕获异常后会走独立的异常处理流程直接返回Response跳过了正常的中间件管道。解决办法是在异常处理类里也加上CORS头。在app/ExceptionHandle.php里重写render方法public function render($request, Throwable $e): Response { $response parent::render($request, $e); $response-header([ Access-Control-Allow-Origin $request-header(origin, *), Access-Control-Allow-Credentials true, Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS, Access-Control-Allow-Headers Authorization, Content-Type, X-Token, ]); return $response; }这个细节如果你不处理会出现一个特别迷惑的现象接口在Postman里测试好好的浏览器里业务正常请求也没问题但一旦某个请求触发了参数校验错误浏览器就报CORS error然后你开始怀疑是不是参数传错了最后排查半天发现是异常响应的跨域头丢了。3. Vue端配置Vite代理和axios必须配合好3.1 Vite代理配置详解现在Vue3项目基本都是Vite构建了Vite的代理配置写在vite.config.js里。我直接说最常用的配置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 3000, host: true, proxy: { /api: { target: http://localhost:80, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } })这个配置的含义是前端所有以/api开头的请求Vite开发服务器会转发到http://localhost:80同时把路径里的/api前缀去掉。这里解释几个关键项有同学照抄了配置但不知道含义出了问题就不知道怎么调。target是后端接口的真实地址。如果你的ThinkPHP运行在小皮面板上端口是80那就填http://localhost:80。如果用的是php think run命令那就是http://localhost:8000。这个地址决定了你的请求往哪里转发。changeOrigin必须设为true。这个参数的作用是修改请求头里的Host字段为目标域名。你的页面跑在localhost:3000直接向后端转发时Host是localhost:3000如果ThinkPHP那边做了域名校验或者二级域名解析就会被拒绝。设为true后Host会变成localhost:80后端感觉就像在直接服务这个请求。rewrite是否启用要看后端路由规则。如果ThinkPHP的路由里没有/api前缀那必须把/api重写掉如果你后端所有控制器都挂在/api路由组下那就不需要这行。有个细节特别容易坑到人server.proxy只在开发环境生效打包之后你部署到Nginx上这个配置直接被无视。所以千万别指望前端配置能解决生产环境的跨域。3.2 vue-cli项目的proxy配置如果你还在维护老项目用的是vue-cliwebpack配置在vue.config.js里module.exports { devServer: { port: 3000, proxy: { /api: { target: http://localhost:80, changeOrigin: true, pathRewrite: { ^/api: } } } } }逻辑和Vite的proxy几乎一样只是字段名从rewrite变成了pathRewrite。要注意的是改完vue.config.js必须重启devServerwebpack不会热加载这个配置文件我记得这一点经常有人不知道改完刷新页面发现配置没生效狂刷新浏览器其实重启一下服务就好了。3.3 axios的baseURL和拦截器配置代理配好了前端请求也不能随便发。如果axios的baseURL或者请求路径写死了后端地址代理就形同虚设。举个反例// 错的做法绕过了代理直接请求后端地址 axios.get(http://localhost:80/api/user/info)这样做代理根本不拦截浏览器直接发请求到localhost:80跨域错误照旧。正确做法是统一走代理前缀// axios实例 const service axios.create({ baseURL: /api, timeout: 15000 }) // 请求拦截器 service.interceptors.request.use( config { const token localStorage.getItem(token) if (token) { config.headers[Authorization] Bearer token config.headers[X-Token] token } return config }, error Promise.reject(error) ) // 响应拦截器 service.interceptors.response.use( response { const res response.data if (res.code ! 200) { // 业务错误处理 return Promise.reject(new Error(res.msg)) } return res }, error { if (error.response error.response.status 401) { // 登录态失效处理 } return Promise.reject(error) } ) export default service注意这里baseURL的值是/api配合Vite代理配置实际上请求会被转发到http://localhost:80并把/api去掉。如果你的代理配置里没有rewrite那其实是把请求转发到http://localhost:80/api/...那ThinkPHP后台就需要在路由组/api下面处理。所以Vite端的rewrite和ThinkPHP路由规则必须前后对得上不然就会出现404。3.4 代理配好之后怎么确认请求真的走了代理这问题对应到一个热词vue配置跨域代理后如何获取我的真实的请求地址。排查这个问题的场景经常是接口通了但后端日志里看到的访问路径不对或者前端想确认代理到底重写成了什么。最直接的办法是看浏览器Network面板。打开开发者工具切到Network点击你要排查的请求。看Request URL如果代理生效它显示的是http://localhost:3000/api/user/info这种前端同源地址不会直接显示后端地址。但Network里显示的地址只是前端发出的地址不是被代理转发后的真实后端地址。要去后端确认最可靠的是看ThinkPHP的日志。TP6的日志默认在runtime/log/目录下里面会记录每一条请求的完整URL、请求方法、请求时间。如果代理配置了rewrite日志里显示的路径就不带/api前缀。另外还可以在Vite配置里临时加一个configure回调proxy: { /api: { target: http://localhost:80, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ), configure: (proxy) { proxy.on(proxyReq, (proxyReq, req, res) { console.log(代理转发请求: , req.url, - , proxyReq.path) }) } } }proxyReq事件会在代理转发请求时触发控制台会打印转发的目标路径。排查看不到真实请求地址的问题时这一招比什么方法都好使。4. 生产环境部署去掉Vite代理后跨域就这么处理4.1 Nginx反向代理配置项目上线后没有Vite帮你转发请求了。最常见的部署方案是把Vue打包后的dist目录丢到Nginx然后让Nginx在同一份配置里既跑前端静态资源又代理API请求到ThinkPHP。假设你的域名是www.example.comVue静态文件在/var/www/distThinkPHP接口运行在http://127.0.0.1:80或者另一台服务器http://backend-server。Nginx配置可以这样写server { listen 80; server_name www.example.com; # Vue静态资源 root /var/www/dist; index index.html; # 前端路由history模式必须加 location / { try_files $uri $uri/ /index.html; } # API反向代理 location /api/ { proxy_pass http://127.0.0.1:80/; 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; } }关键在于location /api/块。proxy_pass http://127.0.0.1:80/;末尾带了一个/这表示把URL里匹配的/api/前缀去掉后再转发。比如请求的是/api/user/info代理转发给后端的实际路径是/user/info。这跟Vite的rewrite是同一个逻辑。如果你希望后端保留/api前缀把proxy_pass改成http://127.0.0.1:80;即可末尾不带/。具体用哪种依然取决于你ThinkPHP的路由定义。这里还要注意一个坑如果Vue路由用了history模式没有#号那种URL必须在location /里配置try_files $uri $uri/ /index.html;否则用户直接访问www.example.com/user/center这种前端路由时Nginx会找服务器的真实文件找不到就返回404。这是Vue部署最常见的坑之一很多同学问为什么Vue打包装好后刷新就404就是这行配置没写。4.2 没有Nginx代理时的纯CORS方案有些情况没办法用Nginx转发比如Vue静态文件托管在CDN或者对象存储上API在独立服务器前端页面和接口完全不在同一个域下。这时候就必须靠后端CORS来解决。实际上ThinkPHP后端的CORS中间件在生产环境同样生效。只要你在Nginx里没有代理、直接请求接口域名时后端返回的响应头里带上了Access-Control-Allow-*浏览器就会放行。但纯CORS方案有个体验问题——请求会分成两步先OPTIONS预检再正式请求网络请求量翻倍。所以如果条件允许我还是建议用Nginx代理至少在生产环境里代理是成本最低、速度最快的方案。4.3 打包后布局异常的排查思路热词里有一条vue 打包后 布局异常我顺手讲一下因为这个问题经常和跨域配置同时出现在部署阶段很多人会以为是跨域导致的。Vue打包后布局异常90%以上是静态资源路径问题。默认情况下Vite打包的资源路径是绝对路径/assets/xxx如果你的前端文件不是部署在域名根目录而是部署在www.example.com/project/这种子目录下绝对路径就找不到资源文件于是页面CSS全部加载失败看起来就是布局崩了。解决办法是在vite.config.js里设置baseexport default defineConfig({ base: ./, // 使用相对路径 plugins: [vue()] })设置成./后打包后的资源引用会变成相对路径无论把dist部署到哪个子目录下都能正常加载。如果部署在Nginx子目录同时还要在Nginx location里配置try_files时带上子目录前缀这里不是跨域问题我就不展开说了。5. 踩坑实录跨域请求的常见问题与排查技巧5.1 问题配置完还是报CORS error我见过太多人卡在这一步后端header加了前端proxy也配了结果还是报Access-Control-Allow-Origin错误。这时候先不要改代码按这个顺序排查第一步打开浏览器的Network面板看报错的请求。区分一下它是OPTIONS还是实际的GET/POST请求。如果是OPTIONS挂了问题几乎一定在后端预检处理上重点检查后端是否拦截了OPTIONS、是否返回204。如果是GET/POST挂了重点看浏览器的Console报错信息它会告诉你是少了Access-Control-Allow-Origin还是Access-Control-Allow-Headers。第二步确认前端请求到底有没有走代理。如果Network面板里请求URL显示的是http://localhost:80/api/xxx说明代理没生效axios的baseURL被写死成后端地址了。如果显示的是http://localhost:3000/api/xxx说明代理在拦截。第三步检查后端日志确认请求有没有真正到达ThinkPHP。如果TP日志里压根没有这条请求记录说明请求在代理层就被拦截了这时候要检查Vite的target地址能不能通。5.2 问题跨域Cookie带不上登录态保存不了跨域请求默认是不携带Cookie的。如果你前后端分离但登录态存在Cookie里你会遇到一个诡异的现象登录接口返回成功Set-Cookie也发了但浏览器就是不存导致后续请求全部401。要解决必须同时满足三个条件前端axios请求设置withCredentials: true或fetch的credentials: include后端Access-Control-Allow-Origin不能是*必须是具体的域名后端Access-Control-Allow-Credentials必须为trueaxios实例创建时加上const service axios.create({ baseURL: /api, timeout: 15000, withCredentials: true })或者使用默认配置axios.defaults.withCredentials true如果你的项目登录态是用TokenlocalStorage存储而不是Cookie那这个坑可以完美避开。个人建议能走Token就不要走跨域Cookie省一大串麻烦。5.3 问题带了自定义Header的请求全被浏览器拦截这个问题很典型。前端在拦截器里加了config.headers[X-Token] token去传用户凭证结果发现所有带这个Header的请求都会被浏览器拦截报错信息里明确写着Request header field x-token is not allowed by Access-Control-Allow-Headers in preflight response.原因就是后端Access-Control-Allow-Headers没把X-Token加进去。有些同学只写了Authorization, Content-Type前端实际用的是X-Token自然被拦。解决方式很简单把后端允许的Headers列表补全Access-Control-Allow-Headers Authorization, Content-Type, X-Token, X-Requested-With, Accept, Origin,如果你嫌麻烦想通配所有自定义头理论上可以写*但要注意它和Allow-Credentials: true的兼容性问题稳妥起见还是把用到的Header名都列出来反正也就是多写几个字母的事。5.4 问题ThinkPHP开启了二级域名设置后跨域失效有同学项目用上了二级域名比如主站是www.example.com接口所在的模块绑定到api.example.com这时跨域问题会变得比较微妙。首先明确一点www.example.com和api.example.com之间本身就是跨域的因为它们域名不同。即使你通过Nginx把两个域名的请求都转发到同一个ThinkPHP应用浏览器依然会视为跨域请求。其次ThinkPHP的域名绑定是在路由层面处理的跨域配置依然要依赖刚才说的中间件方案。如果配置了域名绑定后跨域失效先检查是不是绑定的域名不在后端允许的Origin列表里。比如中间件里写死了Access-Control-Allow-Origin http://localhost:3000,生产环境换成https://www.example.com如果前端实际域是https://api.example.com调你接口那也会被拦。最稳妥的做法是做一个动态白名单允许你控制的域名都通过$allowedOrigins [ https://www.example.com, https://admin.example.com, http://localhost:3000, ]; $origin $request-header(origin, ); if (in_array($origin, $allowedOrigins)) { $header[Access-Control-Allow-Origin] $origin; }5.5 问题OPTIONS请求在ThinkPHP里返回405有同学后端配置了路由但OPTIONS请求到后端返回的是405 Method Not Allowed。原因也简单——TP路由默认只允许你定义的路由方法和请求方法匹配你定义了Route::post()那OPTIONS请求自然匹配不到加上TP的405异常又提前返回了于是预检请求直接失败。解决方案还是CORS中间件那套因为中间件是在路由匹配之前执行能拦截掉OPTIONS请求直接返回204不进入路由解析阶段。就是这个顺序问题导致很多人在控制器层处理OPTIONS事倍功半。5.6 问题代理配置不生效的检查清单如果你的Vite代理配好了但就是不生效按这个清单逐项排查第一确认Vite服务重启了。修改vite.config.js之后devServer必须重启才生效。有很多同学改完配置只是刷新页面配置压根没有重新加载。第二确认前端发请求时用的是相对路径/api/xxx而不是绝对URLhttp://xxx.com/api。绝对URL不会走代理。第三确认代理键名和请求前缀一致。如果你配置的是/api但前端请求路径是/api/v1/user/info代理是能匹配上的如果你前端请求的是/user/info没有/api前缀代理配置就完全没用。第四确认target地址在后端服务器能正常访问。直接在浏览器打开http://localhost:80看看是不是能访问ThinkPHP的入口页。如果连后端服务都没启动代理转发了也是白搭。5.7 附跨域配置排查速查表现象可能原因排查重点OPTIONS请求报CORS错误后端未处理预检请求或返回状态码不对后端中间件是否拦截OPTIONS并返回204实际业务请求报CORS错误Allow-Origin缺失或headers列表不全后端响应头字段是否正确带了自定义header就报错Allow-Headers缺少对应字段前端自定义Header名是否在后端白名单里请求没走代理直接请求后端axios baseURL写死绝对地址前端请求地址是否以/api开头且相对路径Cookie跨域丢失前端没开withCredentials或后端Origin不是具体域名三条件是否同时满足异常响应也报CORS异常处理类里没加跨域头ExceptionHandle的render方法移动端/小程序直接请求接口跨域策略不适用于非浏览器环境确认环境类型非浏览器可绕过CORS机制6. 最后分享一个小技巧把跨域配置做成一个可复用的模板在多个项目间跳来跳去的时候会发现跨域配置的代码几乎是一样的。我自己是维护了一套可以直接复用的模板新项目拿到了先丢进去能省不少时间。ThinkPHP端的中间件文件我存档了一份放在项目的app/middleware/目录下同时把异常处理类的跨域头也写进了自己的代码片段库。Vite端的代理配置、Nginx的跨域配置也都有模板。不过模板只是第一步每次接入还是要看具体项目的实际情况。比如有的项目需要携带CookieOrigin不能写*有的项目只做公众号网页调用允许的域名就一个有的项目前后端不同域名部署走的就是CORS有的项目同一域名下用Nginx代理后端甚至不需要开CORS。另外多说一句跨域配置涉及前端、后端、运维三层团队协作时最好在接口文档里把跨域约定写清楚后端允许的Headers列表是什么、前端请求是否携带Cookie、生产环境走Nginx代理还是后端CORS。让每个人都知道自己在整个链路里负责哪一环排查问题时不会互相甩锅。我在实际项目里感受到最深的体会是跨域问题看着是配置问题本质上是前端不知道后端怎么接收、后端不知道前端怎么请求的沟通问题。两边各管一摊谁也不清楚对方的链路出了错就只能对着Network面板干瞪眼。把链路捋清楚把每一层的配置都验证过一遍跨域真的只是三分钟的事。
