Vite环境变量与Proxy代理的跨域实战配置

最新推荐文章于 2026-07-15 12:47:57 发布

原创

最新推荐文章于 2026-07-15 12:47:57 发布 · 210 阅读

1. 从“跨域”这个拦路虎说起：为什么你的前端请求总被拒之门外？

大家好，我是老张，一个在前后端领域摸爬滚打了十来年的老码农。今天咱们不聊那些高深莫测的底层原理，就聊聊每个前端开发，尤其是刚入行的朋友，几乎每天都会遇到的“老朋友”——跨域问题。你肯定遇到过这种场景：本地开发环境跑得好好的前端项目，端口是localhost:5173，兴冲冲地去请求后端同事提供的接口，比如http://api.your-company.com/user/list，结果浏览器控制台立马给你甩出一个刺眼的红色错误：“Access to fetch at ‘http://api.your-company.com/user/list‘ from origin ‘http://localhost:5173‘ has been blocked by CORS policy”。得，请求被浏览器无情地拦截了。

这其实就是典型的跨域问题。用大白话讲，就是浏览器出于安全考虑，定下了一个“同源策略”的规矩：一个网页的脚本，默认只能请求和它自己“同源”的资源。什么是“同源”？简单说，就是协议（http/https）、域名（或IP）、端口号这三者必须完全一致。你本地开发服务器在http://localhost:5173，而后端接口在http://api.your-company.com:8080，域名和端口都对不上，浏览器就认为这是两个不同的“源”，为了安全，它就会阻止这次请求。

那怎么办呢？难道每次开发都要把前端代码打包部署到和后端同一个域名下？这显然不现实。所以，我们需要一种在开发阶段就能优雅解决跨域问题的方案。常见的办法有好几种，比如让后端配置CORS（跨域资源共享）头部，或者用Nginx做反向代理。但对于我们前端开发者来说，最顺手、最直接的，莫过于利用构建工具自带的开发服务器代理功能。而Vite，作为当下最火的下一代前端构建工具，它的代理配置不仅强大，而且结合环境变量后，会变得异常灵活和高效。这正是我们今天要深入探讨的：如何玩转Vite的环境变量与Proxy代理，让跨域问题在开发阶段消失得无影无踪。

2. Vite Proxy代理：你的专属“传话员”

在深入配置之前，咱们先得搞清楚Vite的Proxy代理到底是个什么“神仙”，它是怎么工作的。你可以把它想象成你和你朋友之间一个非常靠谱的“传话员”。你想跟你朋友（后端服务器）说点事（发请求），但你们之间隔着一道栅栏（浏览器的同源策略），直接喊话他听不见。这时候，你身边这位传话员（Vite开发服务器）就派上用场了。你对着传话员说（向localhost:5173发请求），传话员转身跑到栅栏另一边，把你的话原封不动地告诉你朋友（转发请求到真实后端），拿到你朋友的回复后，再跑回来告诉你（将响应返回给浏览器）。

关键在于，这个“传话”的过程，浏览器是完全感知不到的。浏览器只知道它向localhost:5173发出了请求，并且从localhost:5173收到了响应，一切符合“同源策略”，所以欣然放行。它并不知道背后的请求已经被“偷梁换柱”地转发到了另一个地址。这就是代理的核心原理：利用服务器之间通信没有同源限制的特点，由开发服务器充当中间人，完成请求的转发，从而绕过浏览器的限制。

Vite基于强大的http-proxy库来实现这个功能，配置起来非常直观。它的工作模式属于“反向代理”。简单区分一下：正向代理是帮客户端（比如我们）去访问外界资源，比如一些网络访问工具；而反向代理是帮服务器接收请求，我们客户端感知不到代理的存在，以为直接访问的就是目标服务器。Vite在开发阶段启动的这个代理服务器，对于我们的浏览器而言，就是它要访问的“目标服务器”，但实际上请求被Vite转发到了别处，所以是反向代理。

理解了这一点，我们就能明白，配置Proxy的本质，就是告诉Vite：“嘿，老兄，以后所有符合某个规则的请求，你别自己处理了，帮我转发到另一个地址去。” 接下来，我们就看看怎么把这个规则写清楚。

3. 手把手配置：从基础代理到动态化改造

光说不练假把式，咱们直接上代码。假设你的后端API地址是 https://api.demo-service.com，你本地前端运行在 http://localhost:5173。现在你想在代码里这样调用API：fetch(‘/api/user/info‘)。很明显，直接调用会变成向 http://localhost:5173/api/user/info 发请求，这当然不是我们想要的。我们需要让Vite把以 /api 开头的请求，都转发到 https://api.demo-service.com。

3.1 最基础的vite.config.ts代理配置

打开你的项目根目录下的 vite.config.ts 文件（如果是JavaScript项目则是 vite.config.js）。我们聚焦在 server.proxy 这个配置项上。

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue' // 以Vue项目为例，根据你的框架调整

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      // 键（规则）：任何以 ‘/api‘ 开头的请求路径
      '/api': {
        target: 'https://api.demo-service.com', // 目标服务器地址
        changeOrigin: true, // 修改请求头中的Origin为目标地址，对于虚拟主机站点通常需要开启
        rewrite: (path) => path.replace(/^\/api/, ''), // 可选：路径重写
      },
    },
  },
})

我来拆解一下这几个关键配置：