Vite 开发环境代理配置详解
下面是一篇适合作为技术博客或文档的文章。
Vite 开发环境代理配置详解
在前后端分离开发中，由于浏览器的同源策略限制，前端访问后端接口时经常会遇到跨域问题。Vite 内置了基于 http-proxy 的开发服务器代理功能，可以非常方便地将接口请求转发到目标服务器，而无需修改后端配置。
本文将全面介绍 Vite 开发环境代理（server.proxy）的配置方式、关键配置项以及最佳实践。
1. 核心配置方式
Vite 的代理配置位于 vite.config.ts（或 vite.config.js）中的 server.proxy。
一个最简单的代理配置如下：
import { defineConfig } from 'vite'
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true
}
}
}
})此时：
浏览器请求：
http://localhost:5173/api/user
↓
Vite Dev Server
↓
http://localhost:8080/api/user整个请求过程浏览器并不知道代理的存在，因此不会产生跨域问题。
如果需要配置多个代理，只需要继续添加即可：
server: {
proxy: {
'/api': {
target: 'http://localhost:8080'
},
'/upload': {
target: 'http://localhost:9000'
},
'/socket': {
target: 'ws://localhost:3001',
ws: true
}
}
}不同路径会根据匹配规则转发到不同的服务器。
2. 关键配置项详解
Vite 的 server.proxy 实际上使用的是 http-proxy，因此支持大量配置项。下面介绍最常用的几个。
2.2 目标服务器配置
target 用于指定代理请求最终转发到哪台服务器。
例如：
proxy: {
'/api': {
target: 'http://localhost:8080'
}
}访问：
GET /api/user最终会请求：
http://localhost:8080/api/usertarget 可以配置为：
target: 'http://localhost:8080'
target: 'https://api.xxx.com'
target: 'http://192.168.1.100:9000'如果目标服务器使用 HTTPS 并且证书不受信任，可以关闭 SSL 校验：
proxy: {
'/api': {
target: 'https://test.xxx.com',
secure: false
}
}2.3 请求头修改
默认情况下，请求头中的 Host 保持浏览器原来的地址。
例如：
Host: localhost:5173很多后端服务器会根据 Host 判断请求是否合法，因此通常都会开启：
changeOrigin: true完整示例：
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true
}
}开启后：
Host
localhost:5173
↓
localhost:8080除此之外，还可以通过 configure 或 headers 修改请求头：
proxy: {
'/api': {
target: 'http://localhost:8080',
headers: {
token: '123456'
}
}
}或者：
configure(proxy) {
proxy.on('proxyReq', (proxyReq) => {
proxyReq.setHeader('token', '123456')
proxyReq.setHeader('version', '1.0')
})
}这种方式适用于统一添加 Token、调试标识或自定义 Header。
2.4 路径重写规则
很多后端接口实际上并不存在 /api 前缀，因此需要重写请求路径。
例如：
浏览器：
/api/user/list后端：
/user/list可以使用：
proxy: {
'/api': {
target: 'http://localhost:8080',
rewrite(path) {
return path.replace(/^\/api/, '')
}
}
}请求过程：
浏览器
/api/user/list
↓
rewrite
/user/list
↓
目标服务器如果需要替换为新的前缀：
rewrite(path) {
return path.replace(/^\/api/, '/v1')
}结果：
/api/user
↓
/v1/user也可以进行更加复杂的路径处理：
rewrite(path) {
return path
.replace('/api', '')
.replace('/old', '/new')
}2.5 自定义请求处理
Vite 提供了 configure 配置，可以直接获取到底层代理实例。
例如：
proxy: {
'/api': {
target: 'http://localhost:8080',
configure(proxy) {
proxy.on('proxyReq', (proxyReq, req) => {
console.log('请求：', req.url)
})
proxy.on('proxyRes', (proxyRes, req) => {
console.log('响应：', proxyRes.statusCode)
})
proxy.on('error', (err) => {
console.error(err)
})
}
}
}常见用途包括：
- 请求日志记录
- 修改请求 Header
- 修改 Cookie
- 监听代理异常
- 接口调试
- 打印请求耗时
例如自动增加请求时间：
configure(proxy) {
proxy.on('proxyReq', (proxyReq) => {
proxyReq.setHeader('request-time', Date.now())
})
}3. 路径匹配优先级
Vite 会根据 proxy 中定义的路径进行匹配。
例如：
proxy: {
'/api/admin': {
target: 'http://localhost:9000'
},
'/api': {
target: 'http://localhost:8080'
}
}请求：
/api/admin/user会匹配：
/api/admin而不是：
/api因此建议遵循以下原则：
- 优先配置更具体的路径。
- 再配置通用路径。
- 避免不同代理规则之间发生覆盖。
例如：
proxy: {
'/api/admin': {},
'/api/user': {},
'/api': {}
}这种写法可读性更强，也能避免匹配冲突。
4. 生产环境对比
需要特别注意的是，Vite 的 server.proxy 仅在开发环境生效。
开发环境：
Browser
↓
Vite Dev Server
↓
Backend生产环境：
Browser
↓
Nginx
↓
Backend也就是说，当项目执行：
vite build生成静态资源后，代理配置不会被打包到最终产物中。
生产环境通常采用以下方案：
- 使用 Nginx 配置反向代理。
- 使用 Apache、Caddy 等 Web 服务器进行代理。
- 通过网关（如 Spring Cloud Gateway、Kong、Traefik）统一转发请求。
- 前端直接请求配置好的 API 域名。
因此，开发环境中的代理配置主要用于提升开发效率，而生产环境应依赖服务器或网关实现接口转发。
5. 完整配置示例
下面是一个功能较为完整的 vite.config.ts 配置示例：
import { defineConfig } from 'vite'
export default defineConfig({
server: {
port: 5173,
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
secure: false,
rewrite(path) {
return path.replace(/^\/api/, '')
},
configure(proxy) {
proxy.on('proxyReq', (proxyReq) => {
proxyReq.setHeader('token', '123456')
})
proxy.on('proxyRes', (proxyRes, req) => {
console.log(req.url, proxyRes.statusCode)
})
proxy.on('error', (err) => {
console.error(err)
})
}
},
'/upload': {
target: 'http://localhost:9000',
changeOrigin: true
},
'/socket': {
target: 'ws://localhost:3001',
ws: true
}
}
}
})该配置涵盖了日常开发中最常见的代理需求，包括 HTTP 接口转发、WebSocket 代理、请求头修改、路径重写、HTTPS 支持以及代理事件监听，能够满足绝大多数前后端分离项目的开发场景。
总结
Vite 的代理功能本质上是开发服务器提供的一层反向代理能力，通过 server.proxy 可以轻松解决跨域问题，并支持目标服务器配置、请求头修改、路径重写以及自定义请求处理等高级能力。需要注意的是，它仅在开发环境生效，生产环境仍应依赖 Nginx、网关或其他反向代理方案完成请求转发。熟练掌握这些配置，不仅能够提升本地开发效率，还能使开发环境更加贴近真实的生产部署架构。