当前位置：首页 > news >正文

Vite代理配置完全指南 – 解决跨域问题的最佳实践

news 2025/9/6 14:50:27

什么是 Vite 代理

Vite 的代理功能是基于 http-proxy-middleware 实现的，它允许开发服务器将特定的请求代理到另一个服务器。这在开发环境中非常有用，特别是当你需要：

解决跨域问题
模拟后端 API
代理到不同的开发/测试环境
处理认证和授权

基础配置

在 vite.config.js 中配置代理：

import { defineConfig } from "vite";export default defineConfig({server: {proxy: {// 将 /api 开头的请求代理到 http://localhost:3000"/api": {target: "http://localhost:3000",changeOrigin: true,},},},
});

代理配置选项详解

1. target

类型: string
必需: 是
说明: 目标服务器地址

'/api': {target: 'http://localhost:3000'  // 目标服务器
}

2. changeOrigin

类型: boolean
默认值: false
说明: 是否改变请求头中的 origin 字段

'/api': {target: 'http://localhost:3000',changeOrigin: true  // 推荐设置为 true
}

3. rewrite

类型: function | object
说明: 重写请求路径

'/api': {target: 'http://localhost:3000',rewrite: (path) => path.replace(/^\/api/, '')  // 移除 /api 前缀
}// 或者使用对象形式
'/api': {target: 'http://localhost:3000',rewrite: {'^/api': '/v1'  // 将 /api 替换为 /v1}
}

4. configure

类型: function
说明: 自定义代理配置

'/api': {target: 'http://localhost:3000',configure: (proxy, options) => {proxy.on('error', (err, req, res) => {console.log('代理错误:', err)})proxy.on('proxyReq', (proxyReq, req, res) => {console.log('发送请求到目标服务器:', req.method, req.url)})}
}

5. headers

类型: object
说明: 添加自定义请求头

'/api': {target: 'http://localhost:3000',headers: {'X-Custom-Header': 'value','Authorization': 'Bearer token'}
}

6. secure

类型: boolean
默认值: true
说明: 是否验证 SSL 证书

'/api': {target: 'https://api.example.com',secure: false  // 开发环境可以设置为 false
}

7. ws

类型: boolean
默认值: false
说明: 是否代理 WebSocket 连接

'/socket.io': {target: 'ws://localhost:3001',ws: true
}

8. timeout

类型: number
说明: 代理超时时间（毫秒）

'/api': {target: 'http://localhost:3000',timeout: 5000  // 5秒超时
}

常见问题与解决方案

问题一：跨域问题

问题描述: 即使配置了代理，仍然出现跨域错误。

解决方案:

'/api': {target: 'http://localhost:3000',changeOrigin: true,  // 确保设置为 truesecure: false,       // 如果是 HTTPS，设置为 falseheaders: {'Access-Control-Allow-Origin': '*','Access-Control-Allow-Methods': 'GET,PUT,POST,DELETE,OPTIONS','Access-Control-Allow-Headers': 'Content-Type, Authorization'}
}

问题二：WebSocket 连接问题

问题描述: WebSocket 连接无法建立。

解决方案:

'/socket.io': {target: 'ws://localhost:3001',ws: true,  // 必须设置为 truechangeOrigin: true
}

问题三：大文件上传超时

问题描述: 上传大文件时出现超时。

解决方案:

'/upload': {target: 'http://localhost:3000',changeOrigin: true,timeout: 30000,  // 30秒超时configure: (proxy, options) => {proxy.on('proxyReq', (proxyReq, req, res) => {// 设置更长的超时时间proxyReq.setTimeout(30000)})}
}

问题四：路径重写问题

问题描述: 路径重写不生效。

解决方案:

'/api': {target: 'http://localhost:3000',changeOrigin: true,// 使用函数形式确保正确重写rewrite: (path) => {console.log('原始路径:', path)const newPath = path.replace(/^\/api/, '')console.log('重写后路径:', newPath)return newPath}
}