Vite项目实战：5分钟搞定跨域代理配置（附环境变量最佳实践）
Vite项目实战：5分钟搞定跨域代理配置（附环境变量最佳实践）
每次启动本地开发服务器，看着浏览器控制台里那个刺眼的CORS错误，是不是感觉开发节奏瞬间被打断？对于习惯了Vite闪电般热更新的前端开发者来说，跨域问题就像高速公路上突然出现的路障，让人不得不停下来处理。其实，在Vite生态里，解决这个问题远比想象中简单直接。今天我们不谈复杂的理论堆砌，就从你手头的vite.config.ts文件出发，用最实战的视角，拆解如何快速、优雅地配置代理，并让它能智能适应你从开发到上线的全流程环境。
1. 跨域的本质与Vite的解决思路
在深入配置之前，我们有必要花几分钟理解一下，为什么本地localhost:5173去请求另一个域名的API会被浏览器阻止。这源于浏览器的同源策略，一个出于安全考虑的设计。简单来说，当协议（http/https）、域名、端口号三者有任一不同，浏览器就会判定为跨域请求，并默认拦截其响应。
对于本地开发而言，后端API服务可能运行在另一个端口（如3000），或者部署在测试服务器（如api.test.com）上。直接从前端页面发起请求，必然触发跨域限制。
注意：同源策略是浏览器的行为，服务器与服务器之间的通信并不受此限制。这正是代理服务器能够解决问题的关键。
Vite内置的开发服务器基于http-proxy中间件，它允许我们在本地创建一个“中转站”。这个中转站（代理服务器）与你的前端页面同源（都来自localhost:5173），它负责接收前端的请求，然后以自己的身份去请求真正的后端服务器，拿到数据后再原路返回给前端。对浏览器而言，整个过程就像是在请求同源资源，从而完美绕过了跨域限制。
这种方案的几个核心优势在于：
- 对前端代码零侵入：你无需修改任何业务代码中的请求URL。
- 配置灵活：可以轻松处理路径重写、超时设置、WebSocket代理等复杂场景。
- 环境无缝切换：结合环境变量，可以一套配置适应开发、测试、生产等多环境。
2. 核心实战：五分钟配置基础代理
让我们立刻动手。假设你的后端API基础地址是https://api.your-service.com，而你在本地开发时，希望所有以/api开头的请求都被代理到这个地址。
首先，打开项目根目录下的vite.config.ts文件。如果你的项目没有这个文件，可能是使用了.js后缀，或者需要你手动创建一个。
接下来，找到或添加server配置项，并在其中配置proxy规则。
// vite.config.ts import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' // 以Vue项目为例，根据你的框架调整 export default defineConfig({ plugins: [vue()], // 重点：服务器配置 server: { port: 5173, // 开发服务器端口，默认即5173 open: true, // 是否自动打开浏览器 // 代理配置 proxy: { // 键（规则）：将以 `/api` 开头的请求进行代理 '/api': { target: 'https://api.your-service.com', // 目标服务器地址 changeOrigin: true, // 修改请求头中的Origin为目标地址，对虚拟主机服务通常必要 rewrite: (path) => path.replace(/^\/api/, ''), // 可选：路径重写 // 更多可选配置... } } } })现在，在你的前端代码中，你可以直接这样请求：
fetch('/api/users').then(...)开发服务器在运行时，会自动将http://localhost:5173/api/users的请求，转发到https://api.your-service.com/users。
配置参数解析：
| 参数 | 类型 | 说明 | 是否必需 |
|---|---|---|---|
target | string | 代理的目标服务器URL。 | 是 |
changeOrigin | boolean | 设置为true时，代理请求的Host和Origin头会被修改为目标target。这对于一些基于主机名验证的后端服务至关重要。 | 推荐为true |
rewrite | (path: string) => string | 一个函数，用于重写请求路径。如上例，移除了前缀/api。 | 可选 |
secure | boolean | 如果目标服务器使用自签名证书或HTTPS配置有问题，可设为false来禁用SSL证书验证。生产环境勿用。 | 默认true |
ws | boolean | 是否代理WebSocket连接。 | 默认false |
一个更贴近真实项目的例子可能包含多个代理规则，用于区分不同的后端服务：
proxy: { // 代理用户服务 '/user-api': { target: 'http://user-service.internal.com:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/user-api/, '/api/v1'), }, // 代理商品服务 '/product-api': { target: 'http://product-service.internal.com:8081', changeOrigin: true, }, // 代理上传服务，且不重写路径 '/upload': { target: 'http://file-service.internal.com:9000', changeOrigin: true, } }3. 进阶：与环境变量深度集成
基础配置在单一环境下工作良好，但现代前端项目通常需要面对多环境：开发、测试、预发布、生产。硬编码的target地址显然不够灵活。这时，环境变量就成了最佳搭档。
Vite使用dotenv从项目根目录的.env文件中加载环境变量。以VITE_开头的变量会被直接注入到import.meta.env中，供客户端代码使用。但对于构建时（如vite.config.ts）需要的变量，我们需要使用Vite提供的loadEnv工具函数。
第一步：创建环境变量文件在项目根目录创建以下文件：
.env– 所有环境的默认值.env.development– 开发环境特有变量（运行vite或vite dev时加载）.env.production– 生产环境特有变量（运行vite build时加载）
.env.development文件内容示例：
# 开发环境 API 地址 VITE_APP_API_BASE_URL = https://dev-api.your-service.com # 开发环境 API 路径前缀 VITE_APP_API_PREFIX = /dev-api.env.production文件内容示例：
# 生产环境 API 地址 VITE_APP_API_BASE_URL = https://api.your-service.com # 生产环境 API 路径前缀 VITE_APP_API_PREFIX = /api第二步：在vite.config.ts中动态加载配置我们需要根据当前运行的**模式（mode）**来加载对应的环境变量。defineConfig的回调函数会接收一个包含mode和command的参数对象。
// vite.config.ts import { defineConfig, loadEnv } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig(({ mode, command }) => { // loadEnv 会加载 .env, .env.local, .env.[mode], .env.[mode].local 文件 // process.cwd() 返回项目根目录 const env = loadEnv(mode, process.cwd(), 'VITE_APP_') // 第三个参数是前缀过滤器 console.log(`当前模式: ${mode}, 命令: ${command}`) console.log('API地址:', env.VITE_APP_API_BASE_URL) return { plugins: [vue()], server: { proxy: { // 使用环境变量动态构造代理规则 [env.VITE_APP_API_PREFIX || '/api']: { target: env.VITE_APP_API_BASE_URL, changeOrigin: true, rewrite: (path) => path.replace( new RegExp(`^${env.VITE_APP_API_PREFIX || '/api'}`), '' ), } } }, // 你也可以将环境变量注入到客户端代码的全局变量中（Vite默认已处理VITE_前缀变量） define: { __APP_ENV__: JSON.stringify(env.VITE_APP_API_BASE_URL) } } })通过这种方式，当你运行vite dev（默认mode=development）时，它会自动使用开发环境的API地址；而运行vite build（默认mode=production）时，则使用生产环境地址。代理配置也随之动态变化。
4. 处理复杂场景与调试技巧
基本的代理配置能解决80%的问题，但遇到一些特殊场景时，可能需要更精细的控制。
场景一：代理WebSocket连接如果你的应用使用了WebSocket，并且后端WS服务也在不同的域，同样需要代理。
proxy: { '/socket.io': { target: 'ws://localhost:3000', ws: true, // 关键：启用WebSocket代理 changeOrigin: true, }, '/api': { ... } }场景二：忽略SSL证书错误（仅限开发）在开发阶段，后端可能使用自签名证书，导致代理请求失败。可以临时关闭证书验证。
proxy: { '/api': { target: 'https://localhost:8443', changeOrigin: true, secure: false, // 接受不安全的HTTPS证书 } }场景三：自定义请求头或响应头有时需要向后端传递特定的头信息，或者修改来自后端的响应头。
proxy: { '/api': { target: 'https://api.example.com', changeOrigin: true, configure: (proxy, _options) => { // 可以在代理请求发出前添加自定义头 proxy.on('proxyReq', (proxyReq, req, _res) => { proxyReq.setHeader('X-Special-Dev-Header', 'frontend-local'); }); // 可以在收到响应后修改响应头 proxy.on('proxyRes', (proxyRes, req, _res) => { proxyRes.headers['access-control-allow-origin'] = '*'; }); } } }调试技巧：当代理不生效时，别急着怀疑人生，可以按以下步骤排查：
- 检查控制台：首先确认Vite启动时是否输出了代理配置的日志。你可以在
configure回调中添加日志。 - 核对请求路径：在浏览器开发者工具的Network面板中，检查前端发出的请求URL是否完全匹配你配置的代理规则（如
/api/xxx）。 - 使用
curl或Postman直接测试：绕过浏览器，直接用工具请求http://localhost:5173/api/xxx，看Vite服务器返回什么。同时，直接请求目标target地址，确认后端服务本身是否正常。 - 查看Vite和代理中间件日志：启动Vite时添加
--debug标志（如vite dev --debug）可以获得更详细的日志信息。
5. 构建与生产环境的考量
必须清醒认识到：Vite的server.proxy配置仅在开发服务器（vite dev）运行时生效。当你执行vite build构建出静态文件后，这些代理规则就消失了。
这意味着，对于生产环境，你有两种主流方案：
方案A：API网关/反向代理这是最专业和常见的做法。使用Nginx、Caddy、云服务商的API网关等，在部署层面将特定路径的请求反向代理到后端服务。
# Nginx 配置示例 server { listen 80; server_name your-frontend-app.com; location / { root /path/to/your/dist; # 指向Vite构建的dist目录 try_files $uri $uri/ /index.html; } location /api/ { proxy_pass https://api.your-service.com/; # 代理到后端API proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # ... 其他代理设置 } }这样，用户访问your-frontend-app.com/api/users，Nginx会将其转发到后端，完美解决跨域，且前后端域名统一。
方案B：前端动态配置API基址在前端代码中，根据当前运行环境（通过import.meta.env.MODE或注入的全局变量）动态设置请求的基地址。
// src/utils/request.js const getBaseUrl = () => { if (import.meta.env.PROD) { // 生产环境，使用相对路径或完整的生产环境地址 return import.meta.env.VITE_APP_API_BASE_URL || '/api'; } // 开发环境，Vite代理会处理，这里通常用相对路径或开发地址 return import.meta.env.VITE_APP_API_BASE_URL || '/api'; }; const request = axios.create({ baseURL: getBaseUrl(), timeout: 10000, });然后在构建时，通过.env.production文件注入正确的生产环境API地址。这种方式下，生产环境的请求是浏览器直接发往后端，因此后端服务器必须正确配置CORS头（Access-Control-Allow-Origin等），或者前后端部署在同一域名下。
我个人的经验是，在项目初期或小型项目中，方案B足够简单快捷。但当项目成长，涉及微服务、多环境、灰度发布时，方案A（反向代理）带来的灵活性和控制力是无可替代的。它让前端部署包完全静态化，环境差异的配置压力从构建环节转移到了部署和运维环节，更符合关注点分离的原则。