React/Vue 代理配置全攻略：Vite 与 Webpack 实战指南

前端无涯2025-12-23 18:44

​

在前端开发中，跨域问题 是我们绕不开的坎。浏览器的同源策略限制了不同域名、端口或协议之间的资源请求，而开发环境中前端项目（通常是localhost:3000/localhost:5173）与后端接口（如http://api.example.com）往往不在同一域下，直接请求会触发跨域错误。

为了解决开发环境的跨域问题，主流的前端构建工具（Vite、Webpack）都提供了 ** 代理（Proxy）** 功能。代理的核心原理是：以构建工具启动的开发服务器作为中间层，前端请求先发送到开发服务器，再由开发服务器转发到后端接口服务器（服务器之间的请求不受同源策略限制），最后将后端响应返回给前端，从而绕过浏览器的跨域限制。

本文将详细讲解 React 和 Vue 两大主流框架，分别基于Vite （新一代前端构建工具）和Webpack（传统主流构建工具）的代理配置方案，涵盖基础配置、进阶场景和常见问题排查。

一、Vue 框架的代理配置

Vue 项目的构建工具主要分为两种：Vite （Vue 3 推荐）和Vue CLI（基于 Webpack，Vue 2/3 都支持），两者的代理配置方式略有不同。

1.1 Vue + Vite 代理配置

Vite 的代理配置在项目根目录的vite.config.js（或vite.config.ts）文件中，通过server.proxy选项配置。

基础配置示例

假设前端项目运行在http://localhost:5173，后端接口地址为http://localhost:8080/api，我们希望将前端以/api开头的请求代理到后端接口。

javascript 复制代码 
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  // 开发服务器配置
  server: {
    port: 5173, // 前端项目端口（默认5173，可自定义）
    open: true, // 启动时自动打开浏览器
    // 代理配置
    proxy: {
      // 匹配以/api开头的请求
      '/api': {
        target: 'http://localhost:8080', // 后端接口的基础地址
        changeOrigin: true, // 开启跨域模拟（关键：让后端认为请求来自target域名）
        rewrite: (path) => path.replace(/^/api/, '') // 路径重写（可选：如果后端接口没有/api前缀，需要去掉）
      }
    }
  }
})

配置项说明：

  • target：后端接口的服务器地址（必填）。
  • changeOrigin：是否开启跨域模拟，设置为true时，开发服务器会在转发请求时修改Host请求头为target的域名，避免后端因域名校验拒绝请求（建议始终开启）。
  • rewrite：路径重写函数，用于修改转发到后端的请求路径。例如前端请求/api/user，经过重写后会转发到http://localhost:8080/user（如果后端接口本身带有/api前缀，则不需要此配置）。

测试效果

前端发送请求：

css 复制代码 
// 原本需要直接请求http://localhost:8080/api/user（跨域）
// 现在直接请求/api/user，会被代理转发
fetch('/api/user')
  .then(res => res.json())
  .then(data => console.log(data))

1.2 Vue + Vue CLI（Webpack）代理配置

Vue CLI 基于 Webpack，其代理配置在项目根目录的vue.config.js文件中，通过devServer.proxy选项配置（底层依赖webpack-dev-server的 proxy 功能）。

基础配置示例

需求与上述一致：将/api开头的请求代理到http://localhost:8080。

java 复制代码 
// vue.config.js
module.exports = {
  devServer: {
    port: 8081, // 前端项目端口
    open: true,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        pathRewrite: { '^/api': '' } // 路径重写（与Vite的rewrite作用一致，语法不同）
      }
    }
  }
}

注意 ：Vue CLI 的路径重写使用pathRewrite对象，而 Vite 使用rewrite函数，语法略有差异，但功能一致。

二、React 框架的代理配置

React 项目的构建工具同样分为Vite （新一代）和Create React App（基于 Webpack，简称 CRA，React 官方脚手架）。

2.1 React + Vite 代理配置

React + Vite 的代理配置与 Vue + Vite 完全一致，因为 Vite 的代理功能是框架无关的。

基础配置示例

javascript 复制代码 
// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^/api/, '')
      }
    }
  }
})

2.2 React + Create React App（Webpack）代理配置

CRA 隐藏了 Webpack 的核心配置，因此其代理配置分为两种方式：简单配置（package.json）和进阶配置（setupProxy.js） 。

方式 1：简单配置（package.json）

适用于单一路径的代理场景，直接在package.json中添加proxy字段。

json 复制代码 
{
  "name": "react-app",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  // 简单代理配置：将所有请求代理到http://localhost:8080
  "proxy": "http://localhost:8080"
}

注意：这种方式的局限性很大：

  • 只能配置一个代理目标，无法针对不同路径配置不同代理。
  • 不支持路径重写、HTTPS 等进阶配置。

方式 2：进阶配置（setupProxy.js）

适用于多路径代理、路径重写等复杂场景，需要创建src/setupProxy.js文件，并安装http-proxy-middleware依赖（CRA 已内置该依赖，若未安装可手动执行npm install http-proxy-middleware --save-dev）。

基础配置示例（匹配 /api 路径）
php 复制代码 
// src/setupProxy.js
const { createProxyMiddleware } = require('http-proxy-middleware')

module.exports = function(app) {
  app.use(
    // 匹配以/api开头的请求
    '/api',
    createProxyMiddleware({
      target: 'http://localhost:8080',
      changeOrigin: true,
      pathRewrite: { '^/api': '' }
    })
  )
}
多代理规则示例

如果需要将/api代理到http://localhost:8080，将/admin代理到http://localhost:9090，可以配置多个代理规则：

php 复制代码 
// src/setupProxy.js
const { createProxyMiddleware } = require('http-proxy-middleware')

module.exports = function(app) {
  // 代理/api到8080端口
  app.use(
    '/api',
    createProxyMiddleware({
      target: 'http://localhost:8080',
      changeOrigin: true,
      pathRewrite: { '^/api': '' }
    })
  )
  // 代理/admin到9090端口
  app.use(
    '/admin',
    createProxyMiddleware({
      target: 'http://localhost:9090',
      changeOrigin: true,
      pathRewrite: { '^/admin': '' }
    })
  )
}

注意 ：修改setupProxy.js后，需要重启 CRA 的开发服务器才能生效。

三、代理的进阶配置场景

除了基础的代理配置，我们还会遇到一些复杂场景，比如代理 HTTPS 接口、携带 Cookie、匹配正则路径等。

3.1 代理 HTTPS 接口

如果后端接口是 HTTPS 协议（如https://api.example.com），需要添加secure: false配置，忽略 SSL 证书验证（开发环境下常用，生产环境不建议）。

Vite 配置示例

javascript 复制代码 
proxy: {
  '/api': {
    target: 'https://api.example.com',
    changeOrigin: true,
    secure: false, // 忽略HTTPS证书验证
    rewrite: (path) => path.replace(/^/api/, '')
  }
}

Webpack（Vue CLI/CRA）配置示例

php 复制代码 
// Vue CLI：vue.config.js
proxy: {
  '/api': {
    target: 'https://api.example.com',
    changeOrigin: true,
    secure: false,
    pathRewrite: { '^/api': '' }
  }
}

// CRA：setupProxy.js
createProxyMiddleware({
  target: 'https://api.example.com',
  changeOrigin: true,
  secure: false,
  pathRewrite: { '^/api': '' }
})

如果需要在跨域请求中携带 Cookie（如用户登录状态），需要同时配置前端请求的withCredentials和代理的cookieDomainRewrite。

前端请求配置

csharp 复制代码 
// fetch请求
fetch('/api/user', {
  credentials: 'include' // 携带Cookie
})

// axios请求
axios.get('/api/user', {
  withCredentials: true // 携带Cookie
})

代理配置

javascript 复制代码 
// Vite
proxy: {
  '/api': {
    target: 'http://localhost:8080',
    changeOrigin: true,
    rewrite: (path) => path.replace(/^/api/, ''),
    cookieDomainRewrite: 'localhost' // 将后端返回的Cookie域名重写为前端域名
  }
}

// Webpack
createProxyMiddleware({
  target: 'http://localhost:8080',
  changeOrigin: true,
  pathRewrite: { '^/api': '' },
  cookieDomainRewrite: 'localhost'
})

3.3 正则匹配路径

如果需要匹配更复杂的路径（如以/api/v1或/api/v2开头的请求），可以使用正则表达式作为代理的匹配规则。

Vite 配置示例

javascript 复制代码 
proxy: {
  // 匹配以/api/v开头的请求
  '^/api/v\d+': {
    target: 'http://localhost:8080',
    changeOrigin: true,
    rewrite: (path) => path.replace(/^/api/, '')
  }
}

Webpack（CRA）配置示例

php 复制代码 
app.use(
  // 正则匹配/api/v1或/api/v2
  /^/api/v\d+/,
  createProxyMiddleware({
    target: 'http://localhost:8080',
    changeOrigin: true,
    pathRewrite: { '^/api': '' }
  })
)

四、代理配置常见问题排查

配置代理后，如果请求仍然失败，可从以下几个方面排查：

4.1 代理规则未匹配

  • 检查前端请求的路径是否与代理的匹配规则一致（如前端请求/api/user，代理规则是/api，则匹配；若请求/user，则不匹配）。
  • 正则匹配时，注意正则表达式的语法是否正确（如转义字符、量词等）。

4.2 路径重写错误

  • 如果后端接口没有/api前缀，但代理配置了rewrite: (path) => path.replace(/^/api/, '')，则前端请求/api/user会被转发到/user；若后端接口有/api前缀，去掉重写配置即可。
  • 检查路径重写的语法（Vite 用rewrite函数，Webpack 用pathRewrite对象）。

4.3 changeOrigin 未开启

  • 若后端接口有域名校验（如只允许特定域名访问），未开启changeOrigin: true会导致后端拒绝请求，此时需要开启该配置。

4.4 后端接口地址错误

  • 检查target配置的后端地址是否正确（包括域名、端口、协议），可直接在浏览器中访问后端接口地址，确认接口是否正常。

4.5 开发服务器未重启

  • 修改 Vite/Vue CLI 的配置文件后，开发服务器会自动重启；但修改 CRA 的setupProxy.js后，需要手动重启开发服务器才能生效。

五、总结

开发环境的代理配置是解决跨域问题的最优方案，不同构建工具的配置方式虽有差异，但核心原理一致。

  • Vite ：配置简洁，框架无关，通过server.proxy实现，支持函数式路径重写和正则匹配。
  • Webpack ：Vue CLI 通过devServer.proxy配置，CRA 则分为简单的package.json配置和进阶的setupProxy.js配置，底层依赖http-proxy-middleware。

在实际开发中，我们可以根据项目的框架（React/Vue）和构建工具（Vite/Webpack）选择对应的配置方式，并根据业务需求添加路径重写、HTTPS 支持、Cookie 携带等进阶配置。同时，遇到问题时可按照 "规则匹配→路径重写→跨域配置→接口地址" 的顺序排查，快速定位问题。

最后需要注意：代理配置仅适用于开发环境，生产环境的跨域问题需要通过后端配置 CORS（跨域资源共享）或 Nginx 反向代理来解决。

​

相关推荐
JIngJaneIL3 小时前
基于java+ vue交友系统(源码+数据库+文档)
java·开发语言·前端·数据库·vue.js·spring boot·交友
苹果酱05673 小时前
解决linux mysql命令 bash: mysql: command not found 的方法
java·vue.js·spring boot·mysql·课程设计
拉不动的猪3 小时前
回顾计算属性的缓存与监听的触发返回结果
前端·javascript·vue.js
小七不懂前端4 小时前
我用 NestJS + Vue3 + Prisma + PostgreSQL 打造了一个企业级 sass 多租户平台
前端·vue.js·后端
进击的野人5 小时前
一个基于 Vue 的 GitHub 用户搜索案例
前端·vue.js·前端框架
+VX:Fegn08955 小时前
计算机毕业设计|基于springboot + vue职位管理推荐系统(源码+数据库+文档)
数据库·vue.js·spring boot·后端·课程设计
前端码农一枚5 小时前
Vue3+TypeScript实现手机扫码功能
vue.js·typescript
钱多多8106 小时前
Vue版本降级操作指南（解决依赖冲突与版本不一致问题）
前端·javascript·vue.js·前端框架
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03Linux下V2Ray安装配置指南04在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06Labelme从安装到标注：零基础完整指南07CentOS的ISO镜像下载08Multisim使用教程详尽版--(2025最新版)09Gemini3 生成的基于手势控制3D粒子圣诞树10jdk21下载、安装（Windows、Linux、macOS）