Vite 代理机制详解

基于 http-proxy 的开发服务器代理实现原理

🌐 一句话总结

Vite 的代理是在开发服务器层做的，它拦截浏览器发给 Vite 的请求，转发给真正的后端服务，只在 vite dev 时生效，生产环境不生效。

🔧

核心机制

通过 http-proxy 库实现 HTTP、HTTPS、WebSocket 代理

🌐

跨域解决

开发环境完美解决前端跨域问题

⚡

性能优化

开发服务器层面代理，性能开销小

🎯

精准控制

支持路径重写、请求头修改等高级功能

🔧 实现方式

1. 核心依赖：http-proxy

Vite 内部使用了 http-proxy 这个库（由 Node.js 编写），它是一个强大的 HTTP 代理中间件。

🔗

HTTP/HTTPS

支持标准 HTTP 和 HTTPS 协议

🔄

请求修改

支持修改请求/响应头

🏷️

路径重写

灵活的路径重写功能

🔄 请求流程（开发环境）

浏览器
发送请求
/api/users
↓
Vite 开发服务器
(localhost:3000)
检查 proxy 配置
↓
使用 http-proxy
转发请求
↓
后端服务器
(http://localhost:3001)
返回数据
↓
Vite 服务器
返回给浏览器

✅ 浏览器看到的是：

http://localhost:3000/api/users

✅ 实际请求的是：

http://localhost:3001/api/users

⚙️ 配置方式

配置文件：vite.config.js

// vite.config.js
export default {
  server: {
    proxy: {
      // 代理 /api 开头的请求
      '/api': {
        target: 'http://localhost:3000',  // 后端地址
        changeOrigin: true,               // 修改请求头中的 origin
        rewrite: (path) => path.replace(/^\/api/, ''), // 重写路径
      },
      // 代理 WebSocket
      '/ws': {
        target: 'ws://localhost:8080',
        ws: true,
      }
    }
  }
}

✅ 常见配置项说明

配置项 作用
target 代理的目标地址（后端服务）
changeOrigin 是否修改请求头中的 host 字段（通常设为 true）
rewrite 重写路径，比如去掉 /api 前缀
secure 是否验证 HTTPS 证书（设为 false 可忽略证书错误）
ws 是否代理 WebSocket

🌰 实际例子

假设你前端在 http://localhost:3000，后端在 http://localhost:5000

// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:5000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '/v1') // /api/users → /v1/users
      },
      '/upload': {
        target: 'http://upload-server.com',
        changeOrigin: true,
        secure: false, // 忽略 HTTPS 证书验证
      }
    }
  }
})

请求 /api/users

被代理到 http://localhost:5000/v1/users

请求 /upload/file

被代理到 http://upload-server.com/upload/file

⚠️ 注意事项

⚠️ 只在开发时生效

  • 生产环境（vite build）不会代理
  • 生产环境需要用 Nginx、Caddy 等反向代理

⚠️ 路径匹配规则

  • 路径匹配是前缀匹配
  • /api 会匹配 /api, /api/users, /api/v1/...

⚠️ 功能限制

  • 不支持复杂的路由逻辑
  • 如果需要复杂代理，建议直接用 Nginx 或写自定义中间件

⚠️ WebSocket 配置

  • WebSocket 代理要显式开启
  • 需要设置 ws: true

✅ 总结对比

问题 回答
Vite 代理是通过什么实现的？ http-proxy（Node.js 库）
配置在哪？ vite.config.js 的 server.proxy
生产环境有效吗？ ❌ 只在 vite dev 时生效
能解决跨域吗？ ✅ 是开发时解决跨域的主要方式
支持 WebSocket 吗？ ✅ 设置 ws: true 即可