Vite代理配置：开发服务器与后端API集成
项目地址: https://gitcode.com/GitHub_Trending/vi/vite 1. 开发环境下的跨域痛点与解决方案
在现代前端开发流程中，开发服务器（Development Server）与后端API（Application Programming Interface）的集成是核心环节。当前端应用运行在http://localhost:5173，而后端服务部署在http://localhost:3000时，浏览器的同源策略（Same-Origin Policy）会阻止跨域请求，导致以下常见错误：
Access to fetch at 'http://localhost:3000/api/data' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Vite（发音为 "veet"，意为 "快速的"）作为下一代前端构建工具，内置开发服务器提供了代理（Proxy）功能，可将特定请求转发至后端服务，从而绕过浏览器的跨域限制。其核心原理是：
2. Vite代理配置基础语法
Vite的代理配置通过vite.config.js文件中的server.proxy选项实现。基础配置结构如下：
// vite.config.js
export default {
server: {
proxy: {
// 字符串简写配置
'/api': 'http://localhost:3000',
// 完整配置
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
}
2.1 配置参数详解
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
target | string | - | 目标服务器地址（必填） |
changeOrigin | boolean | false | 是否修改请求头中的Host字段 |
rewrite | function | - | 路径重写规则 |
ws | boolean | false | 是否代理WebSocket连接 |
secure | boolean | true | 是否验证SSL证书 |
pathRewrite | object | - | 路径重写对象（键值对形式） |
configure | function | - | 自定义代理行为 |
3. 实战场景配置案例
3.1 基础API代理
将所有/api开头的请求转发至后端服务：
// vite.config.js
export default {
server: {
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
}
效果：
- 前端请求：
fetch('/api/users') - 实际转发：
http://localhost:3000/users
3.2 多规则代理配置
同时代理API和静态资源：
// vite.config.js
export default {
server: {
proxy: {
// API代理
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
},
// 静态资源代理
'/assets': {
target: 'http://localhost:4000',
changeOrigin: true
}
}
}
}
3.3 WebSocket代理
支持实时通讯场景（如WebSocket）：
// vite.config.js
export default {
server: {
proxy: {
'/ws': {
target: 'ws://localhost:8080',
ws: true,
rewrite: (path) => path.replace(/^\/ws/, '')
}
}
}
}
3.4 条件式代理
根据环境变量动态配置代理：
// vite.config.js
export default ({ mode }) => ({
server: {
proxy: {
'/api': {
target: mode === 'production'
? 'https://api.example.com'
: 'http://localhost:3000',
changeOrigin: true
}
}
}
})
3.5 复杂路径重写
使用正则表达式进行高级路径重写：
// vite.config.js
export default {
server: {
proxy: {
'^/service/(.*)/api/(.*)': {
target: 'http://localhost:3000',
changeOrigin: true,
rewrite: (path) => {
const [, service, resource] = path.match(/^\/service\/(.*)\/api\/(.*)/);
return `/api/${service}/${resource}`;
}
}
}
}
}
4. 代理配置调试与问题排查
4.1 调试技巧
- 启用代理日志：
// vite.config.js
export default {
server: {
proxy: {
'/api': {
target: 'http://localhost:3000',
logLevel: 'debug' // 输出代理日志
}
}
}
}
- 网络请求分析： 使用浏览器开发者工具的Network面板，检查：
- 请求URL是否被正确重写
- 响应头中的
X-Proxy-Bypass标识
4.2 常见问题解决
4.2.1 跨域问题依然存在
解决方案：确保changeOrigin: true，此配置会修改请求头中的Host字段为目标服务器地址。
4.2.2 WebSocket连接失败
解决方案：添加ws: true配置，并检查路径是否正确：
'/ws': {
target: 'ws://localhost:8080',
ws: true,
rewrite: (path) => path.replace(/^\/ws/, '')
}
4.2.3 HTTPS后端服务证书问题
解决方案：开发环境下可禁用SSL验证：
'/secure-api': {
target: 'https://api.example.com',
secure: false, // 不验证SSL证书
changeOrigin: true
}
5. 生产环境部署策略
代理配置仅在开发环境生效，生产环境需采用以下方案：
5.1 后端CORS配置
在后端服务添加CORS头：
// Express.js示例
const express = require('express');
const cors = require('cors');
const app = express();
app.use(cors({
origin: 'https://your-frontend-domain.com',
methods: ['GET', 'POST', 'PUT', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization']
}));
5.2 服务器反向代理
使用Nginx配置反向代理：
# nginx.conf
server {
listen 80;
server_name your-frontend-domain.com;
location /api/ {
proxy_pass http://backend-server:3000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location / {
root /path/to/frontend/dist;
try_files $uri $uri/ /index.html;
}
}
6. 高级配置与性能优化
6.1 代理缓存配置
减少重复请求提升开发效率：
// vite.config.js
export default {
server: {
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
configure: (proxy, options) => {
proxy.on('proxyRes', (proxyRes, req, res) => {
// 添加缓存头
proxyRes.headers['Cache-Control'] = 'public, max-age=60';
});
}
}
}
}
}
6.2 动态代理规则
通过插件实现更复杂的代理逻辑：
// vite.config.js
import { createProxyMiddleware } from 'http-proxy-middleware';
export default {
server: {
proxy: {
'/api': createProxyMiddleware({
target: 'http://localhost:3000',
changeOrigin: true,
pathRewrite: { '^/api': '' },
// 自定义请求拦截
onProxyReq: (proxyReq, req, res) => {
proxyReq.setHeader('X-Dev-Env', 'vite');
}
})
}
}
}
7. 配置验证与测试
7.1 单元测试
使用Vitest测试代理配置：
// proxy.test.js
import { test, expect } from 'vitest';
import { createServer } from 'vite';
test('proxy configuration', async () => {
const server = await createServer({
server: {
proxy: {
'/api': 'http://localhost:3000'
}
}
});
expect(server.config.server.proxy).toHaveProperty('/api');
await server.close();
});
7.2 集成测试
使用Supertest测试代理功能：
// integration.test.js
import request from 'supertest';
import { createServer } from 'vite';
test('proxy /api/users to backend', async () => {
const server = await createServer({
server: {
proxy: {
'/api': {
target: 'http://localhost:3000',
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
});
const { listen } = await server.listen();
const response = await request(listen).get('/api/users');
expect(response.statusCode).toBe(200);
await server.close();
});
8. 总结与最佳实践
8.1 配置清单
- ✅ 始终设置
changeOrigin: true - ✅ 使用
rewrite清理API路径 - ✅ 为WebSocket连接添加
ws: true - ✅ 开发环境禁用HTTPS验证（
secure: false） - ✅ 添加代理日志便于调试（
logLevel: 'debug'）
8.2 性能优化建议
- 代理缓存：对静态资源配置合理缓存策略
- 路径精确匹配：避免过度宽泛的代理规则
- 条件代理：根据环境变量动态启用代理
- 批量代理：使用通配符匹配多个路径规则
8.3 未来展望
Vite 5.0将引入的代理增强功能：
- 内置请求缓存API
- 更灵活的路径匹配模式
- 代理请求优先级控制
- 多目标负载均衡
通过合理配置Vite代理，开发者可以实现无缝的前后端集成，显著提升开发效率。掌握这些配置技巧，将帮助你在各类复杂项目中构建稳定高效的开发环境。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
