首页
/ 正文

vite proxy（千字长文）

更新时间: 2025-03-21 09:51:22

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;

《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前，星球内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习，欢迎点击围观

在现代 Web 开发中，前端与后端服务的协作是基础场景。然而，由于浏览器的同源策略限制，前端应用在开发环境下直接请求不同端口或域名的后端接口时，往往会遇到 跨域问题。此时，Vite Proxy 便成为了解决这一痛点的关键工具。它通过在开发服务器中搭建代理层，将前端请求转发到目标后端服务，从而绕过浏览器的安全限制。对于刚接触前端开发的初学者，理解代理机制是迈向全栈开发的重要一步；而对于中级开发者，掌握其高级配置技巧则能显著提升开发效率。

一、代理机制的核心原理

1.1 跨域问题的本质

浏览器的同源策略要求请求的协议、域名、端口必须与当前页面完全一致。例如，前端页面运行在 http://localhost:3000，若直接请求 http://api.example.com:8080/data，即使目标接口允许跨域（CORS），但若后端未正确配置响应头（如 Access-Control-Allow-Origin），仍会触发跨域错误。

1.2 代理的桥梁作用

Vite Proxy 的核心逻辑是充当一个“中间人”：

前端请求：开发环境中的前端应用（如 React/Vue 组件）向 /api/data 发起请求。
代理转发：Vite 开发服务器（默认端口 3000）截获该请求，根据配置规则将其转发到后端真实地址（如 http://api.example.com:8080/data）。
响应返回：后端处理请求后，代理将结果返回给前端，全程对开发者透明。

形象比喻：
代理就像快递公司的中转站，前端的包裹（请求）先寄到中转站（代理服务器），中转站再将其转寄到最终目的地（后端服务），最终包裹返回时也通过中转站回到前端。

二、快速入门：基础配置与实战

2.1 配置文件与语法

在 Vite 项目中，代理配置通过 vite.config.js 完成。核心配置项是 server.proxy，其结构如下：

// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      // 代理路径前缀
      '/api': {
        // 目标地址
        target: 'http://api.example.com:8080',
        // 其他选项（后续详解）
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
});

关键字段说明：

字段名	作用
`target`	后端服务的完整 URL，必须包含协议（如 `http://` 或 `https://`）
`changeOrigin`	是否修改请求的 `Host` 头为 `target` 的域名（解决部分后端鉴权问题）
`rewrite`	动态修改请求路径，例如将 `/api/data` 转换为 `/data`

2.2 第一个代理案例：电商系统

假设我们正在开发一个电商应用，后端接口位于 http://localhost:8080，前端需请求 /products 获取商品数据。此时配置如下：

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

前端代码直接调用 /api/products，Vite 会将其转发到后端的真实路径 /products，避免跨域问题。

三、进阶配置：灵活控制与场景适配

3.1 路径重写的深度应用

当后端接口路径与前端请求路径不一致时，rewrite 函数是关键。例如，后端接口为 /api/v1/data，但前端希望直接通过 /data 访问：

rewrite: (path) => path.replace(/^\/data/, '/api/v1/data'),

比喻：
就像在迷宫中设置传送门，前端的请求路径是入口，代理会自动将其传送到后端的正确出口。

3.2 多代理与复杂场景

一个项目可能需要同时对接多个后端服务。例如，同时代理用户服务和支付服务：

proxy: {
  // 用户服务
  '/user': {
    target: 'http://user-service:3001',
    changeOrigin: true,
  },
  // 支付服务
  '/pay': {
    target: 'https://payment-gateway.com',
    secure: false, // 允许 HTTPs 请求
    ws: true,      // 支持 WebSocket
  },
}

3.3 自定义请求与响应拦截

通过 onProxyReq 和 onProxyRes 钩子，可对请求或响应进行动态修改：

proxy: {
  '/api': {
    target: 'http://backend.com',
    onProxyReq(proxyReq, req, res) {
      // 添加自定义请求头
      proxyReq.setHeader('X-Auth-Token', 'your_token');
    },
    onProxyRes(proxyRes, req, res) {
      // 移除敏感响应头
      delete proxyRes.headers['x-private'];
    },
  },
}

四、常见问题与解决方案

4.1 代理后仍报跨域错误

可能原因：

changeOrigin 未设置为 true，导致后端通过 Host 头识别到请求来自 localhost，而非预期域名。
后端未正确配置 CORS，需检查响应头 Access-Control-Allow-Origin。

解决方案：

在代理配置中强制 changeOrigin: true。
与后端团队沟通，确保接口返回正确的 CORS 头。

4.2 请求路径未被代理捕获

典型场景：
请求 /api/v1/data 被代理，但实际发送到 /api/v2/data 未生效。
检查步骤：

验证 rewrite 函数逻辑是否覆盖所有路径变体。
确保代理规则的路径前缀是 /api 而非 /api/（后者会忽略无尾缀的请求）。

4.3 WebSocket 和 HTTPS 支持

WebSocket：设置 ws: true 启用协议支持。
HTTPS 后端：若目标服务使用 HTTPS，需设置 secure: false（仅开发环境适用，生产环境需证书配置）。

五、性能优化与最佳实践

5.1 减少代理延迟

本地开发环境：尽量让后端服务运行在本地（如 localhost），避免公网网络延迟。
静态资源分离：对无需代理的静态资源（如图片、字体），直接通过 CDN 或本地路径加载。

5.2 配置版本管理

大型项目中，建议将代理配置拆分为独立文件，便于团队维护：

// proxy.config.js
module.exports = {
  '/api': {
    target: 'http://backend.com',
    // ...其他配置
  },
};

// vite.config.js
import proxyConfig from './proxy.config.js';
export default defineConfig({
  server: {
    proxy: proxyConfig,
  },
});

六、实战案例：电商系统全链路代理

6.1 场景描述

某电商平台需同时对接以下服务：

用户服务：http://user-service:3001（需鉴权）
商品服务：http://product-service:3002（支持 WebSocket 实时库存通知）
支付网关：https://payment-gateway.com（HTTPS 接口）

6.2 配置实现

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    proxy: {
      // 用户服务
      '/user': {
        target: 'http://user-service:3001',
        changeOrigin: true,
        onProxyReq(proxyReq) {
          // 自动注入用户 Token（从 localStorage 获取）
          const token = localStorage.getItem('auth_token');
          proxyReq.setHeader('Authorization', `Bearer ${token}`);
        },
      },
      // 商品服务（含 WebSocket）
      '/product': {
        target: 'http://product-service:3002',
        ws: true,
        rewrite: (path) => path.replace(/^\/product/, ''),
      },
      // 支付网关
      '/pay': {
        target: 'https://payment-gateway.com',
        secure: false,
        changeOrigin: true,
      },
    },
  },
});

6.3 前端调用示例

// 请求用户信息
fetch('/user/me')
  .then((res) => res.json())
  .then((data) => console.log('用户数据:', data));

// 订阅库存变化（WebSocket）
const socket = new WebSocket('ws://localhost:3000/product/ws/stock');
socket.onmessage = (event) => {
  console.log('库存更新:', event.data);
};

结论：Vite Proxy 的核心价值与未来展望

Vite Proxy 不仅解决了开发中的跨域痛点，更通过灵活配置为复杂架构提供了无缝衔接的桥梁。对于开发者而言，掌握其核心原理和高级用法，能够显著提升多服务协同开发的效率。未来，随着微服务架构的普及，代理配置的自动化与智能路由将成为优化方向，而 Vite 的生态工具链也在持续演进，为开发者提供更强大的支持。

关键总结：

基础配置：路径映射 + 目标地址是核心
进阶技巧：路径重写、多代理、请求拦截
最佳实践：分离配置、本地化服务、HTTPS 处理

通过本文的讲解，希望读者能系统性地掌握 Vite Proxy 的全貌，并在实际项目中游刃有余地应用这一工具。

vite proxy（千字长文）

一、代理机制的核心原理

1.1 跨域问题的本质

1.2 代理的桥梁作用

二、快速入门：基础配置与实战

2.1 配置文件与语法

关键字段说明：

2.2 第一个代理案例：电商系统

三、进阶配置：灵活控制与场景适配

3.1 路径重写的深度应用

3.2 多代理与复杂场景

3.3 自定义请求与响应拦截

四、常见问题与解决方案

4.1 代理后仍报跨域错误

4.2 请求路径未被代理捕获

4.3 WebSocket 和 HTTPS 支持

五、性能优化与最佳实践

5.1 减少代理延迟

5.2 配置版本管理

六、实战案例：电商系统全链路代理

6.1 场景描述

6.2 配置实现

6.3 前端调用示例

结论：Vite Proxy 的核心价值与未来展望

最新发布

DataGrip 2025.1 最新激活码，破解版安装教程（至2099年~）

Webstorm 2025.1 最新激活码，破解版安装教程（至2099年~）

Pycharm 2025.1 最新激活码，破解版安装教程（至2099年~）

IDEA 2025.1 最新激活码，破解版安装教程（至2099年~）

Cursor @ 符号（千字长文）

POP3 协议（一文讲透）

IMAP 协议（保姆级教程）

RDP 协议（建议收藏）

SFTP 协议（保姆级教程）

UDP 协议（长文解析）