企业官网建设流程全解析

遇到过吧？本地Vue项目跑在5173端口，后端服务跑在8080端口，前端一调接口，浏览器的Network里明明有请求，控制台却一直报CORS错误。页面加载不出来，后端日志里也没看到请求进来。很多人第一反应是让后端加@CrossOrigin，但加了之后又牵出Cookie、预检请求一堆破事。我后来在vite.config.js里配置server.proxy代理，几分钟就把本地跨域问题解决干净了。这篇文章把Vite proxy从原理到实战拆开讲透，包括核心字段解读、多环境管理、排查思路，以及上线后的替代方案，适合正在被本地跨域折腾的Vue + Vite开发者。

1. 跨域问题的根源：请求发出去了，响应回不来

先说一个反直觉的事实：当浏览器拦截跨域请求时，请求大概率已经发出去了，后端也收到了，只是浏览器在拿到响应之后，发现响应头里没有允许跨域的标识，于是直接把响应挡在门外，并把错误抛给前端开发者。

1.1 同源策略：浏览器充当了严格的快递员

同源策略是浏览器最基础的安全机制之一。所谓“同源”，要求协议、域名、端口三者完全一致。以http://localhost:5173为例，只要有一项不同，比如端口换成8080，浏览器就认为这是跨域。

这个策略本身是保护用户的：没有它，任意网站都能随便读取你在其他平台的状态和接口数据。但开发阶段，前端和后端通常会分两个进程跑在本地不同端口，这天然就跨域了。前端在5173，后端在8080，浏览器直接访问后端接口时，就会触发同源策略的拦截。

很多人会问：既然请求已经发出去了，后端也收到了，为什么控制台报的是跨域错误，而不是业务错误？原因很简单：响应虽然到达了浏览器，但浏览器拒绝把响应内容交给JS代码。从JS的角度看，这个请求就是“失败”了。

1.2 后端开CORS为什么只是“能用”而没根治问题

解决跨域最直接的做法是后端配置CORS中间件，比如Spring Boot里加@CrossOrigin，或者在Nginx里追加Access-Control-Allow-Origin头。这在功能上确实能通，但本地开发时我不太推荐把这个当成唯一方案。

原因有几点。第一，CORS配置会写进业务代码或部署配置里，开发、测试、生产环境往往需要不同的允许域名，一旦写死，环境切换时容易漏改。第二，一旦接口需要带Cookie，Access-Control-Allow-Origin不能设置成*，必须指定具体域名，还要额外处理Access-Control-Allow-Credentials，这个联动关系很容易踩坑。第三，如果前端本地起了多个端口，或者后端服务有多个，CORS配置就要维护成列表，随着团队扩张会越来越乱。

更麻烦的是，每次跨域请求还可能会触发OPTIONS预检。预检请求处理不好，后端会返回405或者缺少必要的响应头，调试起来又绕一道弯。所以我的建议是：本地开发阶段，用Vite的proxy代理来绕开跨域，后端不需要关心谁来访问，生产环境再用网关或Nginx统一处理。

1.3 Vite Dev Server代理的工作原理

Vite的proxy本质上是利用了Node.js服务器的转发能力。本地开发时，前端代码跑在Vite Dev Server上，当浏览器请求/api/xxx时，Vite并不直接把这个请求当作静态资源处理，而是根据vite.config.js里的server.proxy配置，把请求转发到目标后端地址。

关键点在于：这个转发过程发生在服务器端，不是浏览器端。浏览器始终只和同源的Vite Dev Server通信，所以不会触发浏览器的同源策略。后端收到的请求，是由Vite服务器发起的，也不存在浏览器跨域拦截问题。响应原路返回，浏览器看起来就像在同源环境下请求一样，控制了跨域错误。

这个过程很像外卖骑手：你下单给平台（Vite Dev Server），平台把订单转给餐厅（后端），餐厅做好饭交给平台，平台再送到你手上。你从头到尾只跟平台打交道，不会因为餐厅和你不在一个地址而投诉。

2. proxy核心配置：vite.config.js逐行拆解

Vite的代理配置并不复杂，核心就是server.proxy对象。但很多项目里，配置往往是从网上复制粘贴的，能用但不知道字段含义，出了问题也不知道从哪改起。这里我把最常用的写法拆开讲。

2.1 一个可以直接跑的最小配置

在项目根目录找到vite.config.js，没有就自己建一个。下面是一份可以直接使用的最小配置：

import { defineConfig, loadEnv } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { host: '0.0.0.0', port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, ''), }, }, }, })

这段配置的含义是：当本地开发服务器收到以/api开头的请求时，把请求转发到http://localhost:8080，并把路径前缀/api去掉。

比如前端的请求地址是/api/user/list，实际转给后端的地址就是http://localhost:8080/user/list。如果后端接口本身就带有/api前缀，那rewrite这行就不用写，直接透传。

2.2 键名匹配规则：路径前缀不是随便写的

proxy对象里的键名，比如/api，是用来匹配请求路径的。这里的匹配规则不是简单的“路径相等”，而是“路径前缀匹配”。也就是说，只要请求路径以/api开头，就会被这个代理规则捕获。

这里要特别注意：如果同时配置了/api和/api/v1，Vite会选择更长的匹配规则。所以多个服务或前缀共存时，把更具体的路径放在前面或者依赖Vite的精确匹配规则，不要自己堆叠容易混淆的前缀。

键名最好和前端请求的统一前缀保持一致。实际项目中，我习惯让axios的baseURL统一设置成/api，这样所有接口请求都会走代理，后端也能通过路径区分业务模块。如果键名和请求前缀对不上，代理就不会生效，具体排查方法后面专门讲。

2.3 rewrite和target：路径怎么改、地址往哪发

target是代理的目标地址，也就是后端服务的实际地址。可以是IP、域名，也可以是http://localhost:8080，甚至还支持https://，只是https场景要注意证书问题。

rewrite接收一个函数，参数是当前请求路径，返回值是改写后的新路径。这个函数里最常用的是正则替换：

rewrite: (path) => path.replace(/^\/api/, '')

含义很简单：如果路径以/api开头，就把它删掉。为什么经常要删？因为前端习惯给所有请求加/api前缀，但后端Controller里定义的路径可能并没有这个前缀，这时代理时去掉就刚好匹配。如果后端接口路径同样以/api开头，那就不写rewrite。

还有一种常见场景，前端路径是/api/v1/user，后端只接受/user，可以这样写：

rewrite: (path) => path.replace(/^\/api\/v1/, '')

2.4 changeOrigin / secure / ws：易被忽略的选项

changeOrigin是我建议一定要开的一个选项。它决定转发请求时，是否把请求头里的Host字段改成目标地址的域名。

后端如果做了域名白名单校验，或者根据Host头生成回调地址，不开changeOrigin就可能拿到localhost:5173，导致校验失败。更严重的是，在一些鉴权场景里，后端生成的临时链接或者Cookie域名会跟着错。所以本地调试时，我一般都会写成true，避免这类隐秘问题。

secure选项适用于目标是https地址的场景。如果目标服务器的SSL证书是自签名或没有正确配置，Vite转发时会因为证书校验失败而报错。这时候把secure设置成false，可以跳过证书校验。注意这仅用于本地开发，生产环境不能这么干。

ws选项用于WebSocket代理。如果接口里要建立ws://或wss://连接，比如实时通知，就必须在对应的代理规则中加上ws: true。否则WebSocket握手请求会被当成普通HTTP请求，连接建立失败。

下面是一个考虑到这些细节的完整示例：

proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, ''), }, '/socket': { target: 'ws://localhost:8082', ws: true, changeOrigin: true, }, }

3. 多环境多后端的代理扩展实践

项目一多，或者环境一多，代理配置就不仅仅是写死一个target的事。开发、测试、联调、本地mock，每种场景都要对应不同的后端地址。如果每次切换环境都要手动改vite.config.js，既麻烦又容易忘了改回来。

3.1 用loadEnv区分开发和生产环境

Vite提供了loadEnv方法，可以在vite.config.js里读取当前模式对应的环境变量。Vite启动时，默认会加载.env、.env.development等文件。

我的做法是，在项目根目录创建.env.development和.env.test等文件，分别写入：

VITE_PROXY_TARGET=http://localhost:8080

VITE_PROXY_TARGET=http://test-api.example.com

然后改造vite.config.js：

import { defineConfig, loadEnv } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd(), '') return { plugins: [vue()], server: { host: '0.0.0.0', port: 5173, proxy: { '/api': { target: env.VITE_PROXY_TARGET || 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, ''), }, }, }, } })

这里loadEnv的第三个参数传了空字符串，表示把环境变量文件里的变量全部读取出来，而不是只读VITE_前缀开头的。这样可以避免一部分配置变量在客户端代码里暴露，又能让vite.config.js拿到。

启动开发服务器时，如果不指定mode，默认是development，会对应读取.env.development。当你执行vite build --mode test时，Vite会切换成test模式，读取.env.test。这个机制不仅可以用在代理配置上，还可以同步控制打包时是否启用mock、是否压缩日志等。

3.2 多个服务前缀的配置拆分

大型项目往往不是单一后端，可能是用户服务、订单服务、文件服务各自独立部署。这时可以在proxy对象里挂多个键名，分别转发到不同地址：

proxy: { '/api/user': { target: 'http://localhost:8081', changeOrigin: true, rewrite: (path) => path.replace(/^\/api\/user/, '/user'), }, '/api/order': { target: 'http://localhost:8082', changeOrigin: true, rewrite: (path) => path.replace(/^\/api\/order/, '/order'), }, '/upload': { target: 'http://localhost:8083', changeOrigin: true, }, }

上面这种写法，让请求路径自带服务标识，每个标识对应独立的目标服务。后端可以根据改写后的路径直接路由到具体Controller，不需要额外网关配置。

不过要注意，键名匹配是前缀匹配。如果配了/api/user，同时也没有更长的冲突路径，那么/api/user/login和/api/user/info都会走到同一个target。如果想再细分，可以继续增加更长的键名，比如/api/user/vip，Vite会优先匹配更长的路径。

3.3 从webpack devServer迁移的速查对照

很多老项目还在用webpack，vue.config.js里通过devServer.proxy配置代理。迁到Vite后，字段几乎一一对应，只是入口和文件格式变了。

最大差别在于pathRewrite和rewrite的写法。webpack里pathRewrite是一个对象，比如：

pathRewrite: { '^/api': '' }

而Vite里的rewrite是一个函数：

rewrite: (path) => path.replace(/^\/api/, '')

迁移时把那行配置换成函数写法即可，其他选项基本可以直接沿用。还有一点，Vite配置文件默认是ESM格式，用export default，而webpack配置是CommonJS的module.exports。从旧项目复制配置过来时，这一行一定要改。

4. 代理不生效的排查链路：按顺序做一遍

代理配置看起来简单，但实际开发中“不生效”的情况非常常见。我见过不少同事卡在代理问题上半小时起步，其实大部分原因就那么几类。与其打开控制台乱猜，不如按下面这个顺序排查一遍。

4.1 改完配置没重启，等于白改

vite.config.js是启动时加载的，不像项目源码那样支持热更新。新增或修改了server.proxy配置后，必须手动重启Vite Dev Server，配置才会重新生效。

很多人改完配置后发现代理还是失败，第一反应是去检查代码，折腾半天最后发现只是没重启。所以我的习惯是：只要动过vite.config.js，第一件事就是把终端里的Vite进程停掉重新跑一遍。如果是Vite 3以上版本，有些配置支持server.watch，但proxy相关改动依然要重启才算数。

重启后注意看终端日志，Vite会输出“Local”“Network”地址。如果有代理配置错误，有些版本还会在控制台直接把错误打印出来。

4.2 请求路径与proxy键名对不上

这是第二常见的问题。比如前端代码里axios请求路径写的是/app/user/list，但proxy对象的键名是/api，那么请求根本不会匹配到代理规则，Vite会把它当成静态资源在本地找，结果当然是404。

要判断是哪一种情况，打开浏览器的Network面板，看请求地址。如果请求URL是http://localhost:5173/app/user/list，且状态码404，那大概率是没有匹配到代理键名。如果请求URL是http://localhost:5173/api/user/list，但状态码200且响应结构不对，那可能是代理生效了，只是rewrite改写后路径和后端路由对不上。

统一约定很重要。我一般会让所有前端请求都使用同一个前缀，比如/api。这样只需要在proxy里配置一个键名，后端也能通过这一个前缀识别前端流量。

4.3 用curl和终端日志验证代理是否生效

当我们在浏览器里访问/api接口时，如果代理已经生效，Vite会打印一条请求日志，包含转发到的目标地址。不同版本格式可能不一样，但一般能看到类似http://localhost:8080/user/list的信息。

如果浏览器控制台不方便看，可以直接在终端里用curl验证：

curl http://localhost:5173/api/user/list

如果返回的是后端的JSON响应，说明代理链路通了。如果返回的是Vite的404页面或者HTML内容，说明请求没有进入代理规则，需要检查键名匹配。

还有一种情况：请求能打通，但状态码报500或后端业务错误。这通常不是跨域问题，而是后端接口本身报错了。用curl直接请求后端地址对比一下，就能快速判断责任在谁。

4.4 配置文件报错的处理

Vite在启动时会加载vite.config.js，如果配置文件本身有语法错误，会直接启动失败。常见的报错包括Failed to load config from ... vite.config.js后面跟着行列号。

我遇到过的原因主要有下面几种：

• 配置文件里写了中文标点或多余逗号。
• 把CommonJS的module.exports和ESM的export default混用了。
• 对象结构少了一个括号。
• 代码里用了某个Node环境下没有的变量，比如直接读取了浏览器的window对象。

如果是ESM模块识别问题，可以把配置文件从vite.config.js改成vite.config.mjs，或者确认package.json里没有设置"type": "commonjs"。Vite官方推荐直接在配置里使用ESM语法，这也是为什么所有示例里都有export default。

如果报错行列号指向某个具体位置，可以先看那一段的括号是否闭合。很多配置对象嵌套深了，少一个括号确实不好找，我通常会把这段代码单独格式化一下再重启。

5. 生产环境没有Vite Dev Server，代理怎么办

在本地开发时，Vite的proxy帮助我们绕过了跨域。但把项目执行vite build之后，产出的是纯静态文件，没有Vite Dev Server在背后转发了。这时候如果前端代码还在请求相对路径/api，部署到服务器上就会直接请求部署域名的/api，大概率也是404。

5.1 为什么build之后的项目不能再依赖vite.config.js

vite build构建出来的静态资源，通常在Nginx、CDN或云服务器上托管，整体是一个静态服务器环境，并不运行Node服务。server.proxy配置只属于开发服务器，构建过程中根本不会把这段代理逻辑打包进去。

所以生产环境的跨域和接口转发，要靠部署层的反向代理来解决。最常见的就是Nginx。前端部署到/usr/share/nginx/html，Nginx监听80或443，当收到/api请求时，用proxy_pass把请求转发给后端服务。浏览器视角里，请求还是发给当前域名，不存在跨域。

5.2 Nginx的proxy_pass和Vite的rewrite如何对应

来看一个典型的Nginx配置：

location /api/ { proxy_pass http://localhost:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

这里proxy_pass http://localhost:8080/;末尾带了一个/，意味着会把/api/前缀去掉。比如请求/api/user/list，转发到后端就是http://localhost:8080/user/list。这个效果和Vite里rewrite: (path) => path.replace(/^\/api/, '')是一模一样的。

如果后端接口本身带/api前缀，那Nginx的proxy_pass末尾就不要加/，直接写成：

location /api/ { proxy_pass http://localhost:8080; }

这样请求路径会原样透传，/api/user/list对应http://localhost:8080/api/user/list，和Vite里不写rewrite的行为一致。

还有WebSocket场景，Nginx需要额外配置升级请求头才能支持ws协议：

location /socket/ { proxy_pass http://localhost:8082/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }

Nginx版本的等价配置和Vite的ws: true实现的目标是同一个：让WebSocket握手成功。

5.3 前端统一管理接口前缀的约定

为了让开发代理和生产的Nginx代理无缝衔接，前端代码里最好把接口前缀固定成一个约定值，不要一个请求写/api，另一个请求又写/app。我习惯在axios实例的baseURL里统一配置：

const request = axios.create({ baseURL: '/api', timeout: 10000, })

这样本地开发时，Vite会按/api前缀代理到后端；生产部署时，Nginx也按/api前缀转发，前后端不需要改任何一行业务代码，只需要调整部署层的转发规则即可。

这里还要注意跨环境变量的问题。如果你在.env.production里配了VITE_API_BASE_URL，让axios使用绝对地址，那么生产环境的接口请求就会直接指向某个具体域名，此时就不需要Nginx再转发/api了。两种方案各有优劣，使用相对路径/api配合反向代理的方式，能最大化保持部署灵活性，我目前更推荐这种相对路径方案。

从开发期的Vite proxy到生产期的Nginx反向代理，本质上都是“反向代理”思路，只是承载者不一样。理解了Vite proxy的字段和作用原理，再看Nginx配置就不会觉得陌生了。

最后再分享一个我自己的使用习惯：vite.config.js里的target地址尽量都通过环境变量读取，不要把具体IP、域名写死在配置文件里。这样团队成员从本地联调切到测试环境时，只需要改对应的.env文件，不需要动代码和配置逻辑。项目多了以后，这套约定会帮你省下大量踩坑时间。