详解Vite 配置中的代理功能

最新推荐文章于 2025-08-05 15:21:50 发布

原创最新推荐文章于 2025-08-05 15:21:50 发布 · 666 阅读

19 ·

CC 4.0 BY-SA版权

文章标签：

#前端

前端专栏收录该内容

5 篇文章

订阅专栏

在前端开发过程中，你可能经常会遇到一个头疼的问题：当你在本地启动的前端项目中调用后端接口时，浏览器控制台会报出类似 “Access to fetch at ‘http://xxx’ from origin ‘http://localhost:3000’ has been blocked by CORS policy” 的错误。这就是跨域问题，而 Vite 的代理功能正是解决开发阶段跨域问题的有效方案。

让我们从一段常见的 vite.config.ts 配置代码说起，看看其中的代理设置到底是如何工作的。
在 Vite 的配置文件中，server 选项用于配置开发服务器的行为，其中的 proxy 属性就是专门用来设置代理规则的。比如这样的配置：

server: {
  host: "0.0.0.0", // 默认为localhost
  port: 7001, // 端口号
  open: false, // 是否自动打开浏览器
  proxy: {
    // 第三方服务器的代理配置
    '/dev-api/PileManager': {
      target: 'http://personalpile.admin.usteu.com/',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/dev-api/, '')
    },
    // 本地后端服务的代理配置
    "/dev-api": {
      target: "http://localhost:8050/",
      changeOrigin: true,
      rewrite: path => path.replace(new RegExp('^' + env.VITE_APP_BASE_API), '/api')
    }
  },
}

首先我们要理解，为什么需要代理。当你的前端项目运行在http://localhost:7001（由 port 指定），而后端接口部署在另一个域名或端口（比如http://localhost:8050）时，由于浏览器的同源策略限制，直接请求会被拦截。代理的作用就是让前端请求先发送到本地的 Vite 开发服务器，再由 Vite 服务器转发到目标后端服务器，这样就避开了浏览器的跨域限制。

我们来看 proxy 对象中的具体配置。这里定义了两组代理规则，每组规则都是一个键值对。键表示需要被代理的请求路径前缀，而值则是该前缀对应的代理配置。

先看第一个代理规则’/dev-api/PileManager’。当你的代码中发起类似fetch(‘/dev-api/PileManager/some/path’)的请求时，Vite 会拦截这个请求，并按照配置进行处理。target 指定了目标服务器的地址，这里是http://personalpile.admin.usteu.com/，意味着这个请求会被转发到该服务器。

changeOrigin 设置为 true 是一个很重要的配置，它表示在发送请求到目标服务器时，会修改请求头中的 Origin 字段，让目标服务器以为请求来自于它自己所在的域，从而避免一些服务器可能存在的域名验证限制。

rewrite 则用于修改请求路径。这里的path.replace(/^/dev-api/, ‘’)表示会把请求路径中开头的/dev-api去掉。原来的请求路径是/dev-api/PileManager/some/path，经过重写后就变成了/PileManager/some/path，然后再拼接上 target 的地址，最终请求的实际地址就是http://personalpile.admin.usteu.com/PileManager/some/path。

再看第二个代理规则"/dev-api"。这里你可能会疑惑，它的路径前缀看起来和第一个规则有重叠，为什么能正常工作？这是因为 Vite 在匹配代理规则时，会优先选择更具体、更长的路径前缀。只有当请求路径不匹配第一个规则时，才会匹配这个更通用的规则。

这个规则的 target 设置为本地的http://localhost:8050/，通常这是开发者自己的后端服务。rewrite 这里使用了env.VITE_APP_BASE_API，这是一个从环境变量中获取的值，通常也是/dev-api。所以这个重写规则的意思是，把请求路径中开头的/dev-api替换成/api。比如原来的请求是/dev-api/user/list，重写后就变成了/api/user/list，最终请求的实际地址是http://localhost:8050/api/user/list。

通过这样的代理配置，前端开发者就不需要在代码中硬编码不同环境的接口地址，也不需要担心开发阶段的跨域问题。Vite 会自动帮我们完成请求的转发和路径的处理，让我们可以专注于业务逻辑的开发。

需要注意的是，这些代理配置只在开发阶段生效，因为它是 Vite 开发服务器提供的功能。当项目打包上线到生产环境时，通常会使用 Nginx 等服务器来配置类似的反向代理功能，以确保生产环境中的接口请求也能正常工作。

那么nginx大概应该怎么配置呢，如下示例：

location /dev-api/PileManager/ {
        proxy_pass http://personalpile.admin.usteu.com/PileManager/;
        proxy_set_header Host personalpile.admin.usteu.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
}

location /dev-api/ {
          proxy_pass http://127.0.0.1:8050/api/;
          # 连接增强配置
          client_max_body_size 1000m;
          send_timeout 3600s;
          keepalive_timeout 3600s;         # 保持连接活性（网页7补充）
          keepalive_requests 10000;       # 单连接最大请求数
          # SSE核心配置
          proxy_http_version 1.1;          # 强制使用HTTP/1.1协议（网页1、网页6）
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          #关闭代理缓冲，确保实时传输
          proxy_buffering off;
          proxy_cache off;                # 关闭缓存防止数据截断
          proxy_read_timeout 86400s;      # 24小时超时（网页1建议值）
          proxy_set_header Cache-Control 'no-cache';
          add_header Cache-Control no-cache;

          # 头信息增强
          proxy_set_header X-Accel-Buffering no;
          # 下面三句话是用来获取用户访问的ip的
          proxy_set_header Host             $host;
          proxy_set_header X-Real-IP        $remote_addr;
          proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
          proxy_set_header Last-Event-ID $http_last_event_id;

          # CORS跨域支持（网页3、网页5）
          add_header 'Access-Control-Allow-Origin' $http_origin always;
          add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
          add_header 'Access-Control-Allow-Headers' 'Content-Type,Authorization,Last-Event-ID' always;
          add_header 'Access-Control-Expose-Headers' 'Content-Type,Content-Length' always;

          # 预检请求处理（网页2、网页6）
          if ($request_method = OPTIONS) {
             add_header 'Access-Control-Max-Age' 1728000;
             add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, Last-Event-ID';
             add_header 'Content-Type' 'text/plain; charset=utf-8';
             return 204;
          }
}