如何在 vite.config.ts 中配置 proxy 代理解决跨域请求问题？

当你在开发环境发起前端请求时，浏览器控制台出现类似“Access-Control-Allow-Origin”的跨域错误，或者后端接口与前端服务不在同一域名或端口下，就需要在 Vite 配置中设置 proxy。注意，仅开发环境有效，生产环境需通过 Nginx 或后端配置解决跨域。这是最常见的判断依据，也是多数前端项目开始接触代理配置的起点。

配置代理的基本写法

在 vite.config.ts 的 defineConfig 中，添加 server.proxy 字段，通常配置一个对象。例如：

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
});

其中 target 为目标服务器地址，changeOrigin 必须设为 true 以支持虚拟主机。rewrite 可选，用于移除前缀。如果你不确定后端是否需要跳转路径，先不要写 rewrite，直接转发带前缀的路径，等确认后再调整。

验证代理是否生效

配置完成后，重启 Vite 开发服务器。在浏览器中打开开发者工具的 Network 标签，发起一个指向代理路径（如 /api/users）的请求。观察请求 URL 是否被正确转发至 target 地址，且状态码为 200 或相应成功码。若仍报跨域，检查 changeOrigin 是否设置，或确认 target 的 CORS 策略。另外，注意查看请求的 Host 头部——如果 changeOrigin 为 false，Host 还是前端域名，某些后端会拒绝请求。

常见配置错误与排查

一个常见问题是忘记设置 changeOrigin: true，导致代理请求的 Host 头部仍为前端地址，某些后端可能会拒绝。另外，路径重写（rewrite）写错也会导致 404。注意正则表达式写法：若 rewrite 返回的新路径错误，请求会找不到资源。建议先注释掉 rewrite 测试是否能正常访问原始路径。还有一种情况是 target 地址写错，比如漏了端口或协议。你可以用 curl 或 Postman 直接请求 target 地址确认后端是否正常，排除代理本身的问题。

风险边界与多规则处理

代理配置仅作用于开发服务器，不可用于生产构建后的静态文件。如果配置多个代理规则，注意路径前缀不要冲突，否则前面的规则会优先匹配。此外，若 target 是 HTTPS 地址，可能需要忽略证书验证（如设置 secure: false），但仅建议在开发环境使用。生产环境一定要用 Nginx 反向代理或后端 CORS 头来处理跨域，不要依赖 Vite proxy。

最后提一个容易被忽略的点：Vite 配置修改后需要重启开发服务器才能生效，热更新不会重新加载 server 配置。如果你改了 proxy 但发现没效果，先终止 dev 命令再重新启动。整体来说，只要按照上述步骤逐步确认，跨域问题在开发环境基本可以靠 proxy 解决。