别再为跨域发愁了！手把手教你用Vite Proxy搞定前后端联调（附完整配置代码）

彻底解决Vite开发环境跨域难题从原理到实战配置指南每次启动前端项目时浏览器控制台那个刺眼的CORS错误是否让你血压飙升作为现代前端开发的核心痛点之一跨域问题困扰着无数开发者。而Vite提供的Proxy解决方案正是破解这一困局的利器。1. 为什么跨域问题总在开发阶段出现当我们在本地启动前端服务通常是localhost:3000并尝试访问后端API可能是api.yourcompany.com或另一个端口时浏览器会严格执行同源策略。这种安全机制阻止了不同源协议、域名、端口任一不同之间的资源请求。典型报错示例Access to fetch at https://api.example.com/users from origin http://localhost:3000 has been blocked by CORS policy传统解决方案如JSONP或CORS配置都需要后端配合而Vite Proxy的妙处在于完全前端自主解决无需修改后端代码配置简单直观支持热更新即时生效2. Vite Proxy核心配置详解在项目根目录的vite.config.js中我们可以这样配置基础代理export default defineConfig({ server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } })2.1 关键参数解析参数类型作用典型值targetstring代理目标地址http://localhost:8080changeOriginboolean修改请求头hosttrue/falserewritefunction路径重写规则path path.replace(...)secureboolean跳过HTTPS验证false开发环境wsbooleanWebSocket代理true如需代理ws实际案例假设后端API基础路径是http://backend:3000/api/v1而前端想用更简洁的/api前缀proxy: { /api: { target: http://backend:3000/api/v1, rewrite: path path.replace(/^\/api/, ), // 其他配置... } }这样前端请求/api/users会被代理为http://backend:3000/api/v1/users3. 多环境代理配置实战现代项目通常需要对接多个环境通过环境变量动态切换代理目标是优雅的解决方案const envConfig { dev: { target: http://localhost:8080 }, test: { target: https://test.api.com }, prod: { target: https://api.com } } export default defineConfig({ server: { proxy: { /api: { ...envConfig[process.env.MODE], changeOrigin: true } } } })配套的package.json脚本{ scripts: { dev: vite, dev:test: MODEtest vite, dev:prod: MODEprod vite } }4. 高级代理技巧与排错指南4.1 WebSocket代理配置对于实时应用WebSocket的代理需要特殊处理proxy: { /socket.io: { target: ws://localhost:3000, ws: true, changeOrigin: true } }4.2 条件代理绕过某些情况下需要动态决定是否代理proxy: { /api: { target: http://localhost:3000, bypass: (req) { if (req.url.includes(/special)) { return /special-proxy.html } } } }4.3 常见问题排查清单代理不生效检查请求路径是否匹配代理规则确认vite服务器已重启配置修改后浏览器开发者工具查看请求URL是否变化HTTPS证书问题proxy: { /api: { target: https://your-api.com, secure: false // 跳过证书验证 } }路径重写异常使用console.log调试rewrite函数检查正则表达式是否准确Cookie丢失问题设置cookieDomainRewrite配置确保后端设置了正确的Access-Control-Allow-Credentials5. 完整配置示例与最佳实践以下是一个企业级项目的完整代理配置示例export default defineConfig({ server: { proxy: { // 基础API代理 /api: { target: env.VITE_API_BASE_URL, changeOrigin: true, rewrite: path path.replace(/^\/api/, /v1), configure: (proxy) { proxy.on(proxyReq, (proxyReq) { proxyReq.setHeader(X-Forwarded-For, 127.0.0.1) }) } }, // 静态资源代理 /assets: { target: env.VITE_CDN_URL, changeOrigin: true }, // WebSocket代理 /realtime: { target: env.VITE_WS_URL, ws: true } } } })性能优化建议对频繁调用的API路径使用更精确的匹配规则生产环境应使用Nginx等专业代理服务器开发环境可以配合vite-plugin-mock创建本地mock数据经过多个项目的实践验证合理的Proxy配置能使开发效率提升30%以上。特别是在微前端架构或BFF层开发中灵活运用路径重写可以大幅简化接口调用复杂度。