Vite 中 vite.config.js 代理配置不生效，如何排查和解决？

Question

Vite 中 `vite.config.js` 代理配置不生效是高频问题，常见原因有：① 未在开发服务器（`vite dev`）下使用——代理仅对 `localhost:5173` 等开发环境生效，生产环境需自行配置反向代理；② 路径匹配不精确，如 `'/api'` 不会匹配 `/api/`（缺少尾斜杠），建议统一加 `/api/` 并启用 `changeOrigin: true`；③ 代理目标地址协议错误（如写成 `http://localhost:3000/` 却被浏览器同源策略拦截，应确保目标服务已启动且允许跨域）；④ 配置位于 `build` 或 `server.hmr` 下而非 `server.proxy`；⑤ 使用了 `rewrite` 但正则或函数逻辑有误。排查建议：开启 `configure: (proxy, options) => console.log(proxy)` 日志，用浏览器 Network 面板确认请求是否发往 `/proxy/xxx` 而非直连后端，并检查控制台是否有 `504` 或 CORS 报错。✅ 正确示例：`'/api/': { target: 'http://localhost:3000', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') }`。

Answer 1

```html

一、基础认知：Vite 代理的本质与作用域边界

Vite 的 server.proxy 是开发服务器（vite dev）内置的 HTTP 代理中间件，基于 http-proxy-middleware@2.x 实现，仅在开发阶段生效（如 http://localhost:5173），完全不参与构建产物或生产部署。生产环境必须通过 Nginx、Caddy、Cloudflare Rules 或后端网关完成反向代理——这是所有失效问题的顶层前提。若在 vite build 后访问 dist 目录并期望代理工作，本质是概念误用。

二、配置定位：代理必须置于正确层级

• ✅ 正确路径：export default defineConfig({ server: { proxy: { '/api/': { ... } } } })
• ❌ 常见错误位置：build.proxy（构建无关）、server.hmr.overlay（热更新 UI）、resolve.alias（路径别名）

可通过启动时日志验证：Vite 会打印 [vite] server proxy: /api/ -> http://localhost:3000 —— 若无此行，说明配置未被识别。

三、路径匹配：精确性决定代理是否触发

配置写法	匹配示例	是否命中	原因
'/api'	/api/users	✅	前缀匹配（默认行为）
'/api'	/api/	❌	路径末尾斜杠未对齐，/api 不匹配 /api/（注意 trailing slash）
'/api/'	/api/users	✅	推荐写法：统一以 / 结尾，语义清晰且兼容 rewrite

四、跨域穿透：changeOrigin 为何不可或缺

当目标服务运行在 http://localhost:3000，而浏览器请求发往 http://localhost:5173/api/users 时，代理会将 Host 请求头保留为 localhost:5173。若后端校验 Host 或依赖原始域名生成 URL（如 JWT issuer、OAuth redirect_uri），将导致 400/500 错误。启用 changeOrigin: true 会重写 Host 头为 localhost:3000，并修正 Referer 和相对路径上下文。

五、协议与连通性：目标服务的可访问性验证

代理失败常被误判为配置问题，实则源于网络层阻断：

1. 确认目标服务已启动：curl -v http://localhost:3000/api/test
2. 检查 CORS 策略：后端需响应 Access-Control-Allow-Origin: * 或明确允许 http://localhost:5173
3. 避免混合协议：若前端为 https://localhost:5173（HTTPS 开发），目标必须也为 HTTPS，否则浏览器主动拦截

六、重写逻辑：rewrite 函数的陷阱与调试技巧

使用 rewrite 时常见错误包括：

• 正则未加全局标志 g 导致多次调用只替换一次
• 未处理路径编码：/api/%E4%B8%AD%E6%96%87 需先 decodeURIComponent 再替换
• 函数返回值非字符串（如返回 undefined）将导致 500 错误

✅ 推荐健壮写法：
rewrite: (path) => decodeURIComponent(path).replace(/^\/api\//, '')

七、诊断流程：结构化排查路径图

flowchart TD
  A[发起请求 /api/users] --> B{Network 面板查看请求 URL}
  B -->|显示 http://localhost:5173/api/users| C[代理未触发：检查 proxy 配置位置 & 启动日志]
  B -->|显示 http://localhost:3000/users| D[代理已转发：检查目标服务日志 & CORS 响应头]
  B -->|显示 504 Gateway Timeout| E[目标不可达：telnet localhost 3000 或 netstat -an | grep :3000]
  C --> F[添加 configure: (proxy) => console.log(proxy)]
  D --> G[检查 Response Headers 中 Access-Control-Allow-Origin]

八、进阶实践：多级代理与条件路由

复杂场景需动态代理逻辑：

'/api/': {
  target: 'http://localhost:3000',
  changeOrigin: true,
  rewrite: (path) => path.replace(/^\/api\//, ''),
  configure: (proxy, options) => {
    proxy.on('error', (err, req, res) => {
      console.error('Proxy error:', err);
      res.writeHead(500, { 'Content-Type': 'text/plain' });
      res.end('Proxy failed');
    });
  }
}

还可结合环境变量实现多环境代理：target: process.env.VITE_API_BASE || 'http://localhost:3000'。

九、生产迁移：从开发代理到 Nginx 反向代理的平滑过渡

开发期代理 ≠ 生产方案。典型 Nginx 配置示例：

location ^~ /api/ {
  proxy_pass http://backend-server/;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

关键点：proxy_pass 末尾的 / 决定路径裁剪行为，必须与 Vite 中 rewrite 逻辑对齐，否则出现 /api/api/users 双重前缀。

十、终极验证清单（Checklist）

1. ✅ 运行的是 vite dev 而非 vite build && serve
2. ✅ server.proxy 在 vite.config.js 根对象内，非嵌套错位
3. ✅ 路径规则以 /xxx/ 形式书写（含起止斜杠）
4. ✅ changeOrigin: true 已启用，且目标服务可直连
5. ✅ Network 面板中请求 URL 显示为 http://localhost:5173/api/... → 触发代理 → 变为 http://localhost:3000/...
6. ✅ 控制台无 CORS policy 报错，响应头含 Access-Control-Allow-Origin
7. ✅ rewrite 函数返回纯净路径字符串，无 undefined 或异常抛出
8. ✅ 使用 configure 捕获代理中间件事件日志
9. ✅ 生产环境已独立部署反向代理，未依赖 Vite 代理机制
10. ✅ 团队文档明确标注 “代理仅限开发” 并附 Nginx 配置模板

```