企业官网建设流程全解析

前几天调一个 Vue3 + TS 项目，vite 开发服务跑得好好的，结果前端页面一调接口就刷屏报错，控制台一堆[vite] http proxy error，紧接着请求全部挂掉。说实话这种“代理报错”在 vite 项目里太常见了，但报错信息写得又晦涩，新人看了直接懵，老手也得翻半天文档。今天不聊理论，就按我实际排查的过程，把 vite 请求代理报错的常见类型、定位方法和修复方案完整拆一遍。

这篇内容适合所有用 vite 做开发服务器、配了 server.proxy 代理的前端同学。不管你是刚搭完 vite 项目还没配过代理，还是已经踩进代理报错的坑里出不来，按下面的流程走，大部分问题都能定位到根因。

1. 先搞清楚代理到底在替我们做什么

1.1 开发阶段的跨域是怎么来的

vite 启动后默认跑在http://localhost:5173，你前端代码里用fetch('/api/login')发请求，浏览器实际请求的地址是http://localhost:5173/api/login。如果后端接口跑在http://localhost:8080，那这个请求本来应该直接发给 8080，但因为你写的是相对路径/api/...，请求就被送到了 5173。

而所谓跨域，本质是浏览器同源策略拦截了“非同源”的响应。开发阶段你不想每次都被跨域卡住，常见的方案就是让前端 dev server 做一次转发：浏览器请求http://localhost:5173/api/login，vite 在服务端收到以后，再代替浏览器去请求http://localhost:8080/api/login，拿到结果后返回给浏览器。因为最终响应是从 5173 端口返回的，浏览器觉得自己请求的是同源地址，跨域问题就这么被绕开了。

这里的关键点是：代理行为发生在服务端，不是浏览器端。所以你改完 vite.config.ts 里的 proxy，不需要刷新页面去“清除浏览器缓存”，而是要确保 dev server 已经加载了最新配置。

1.2 代理配置的基础写法

一个最典型的 vite.config.ts 代理配置长这样：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } })

这段配置的含义是：所有以/api开头的请求路径，统一转发到http://localhost:8080。changeOrigin: true表示转发时改写请求头里的 Host 字段，让后端以为是自己在被直接访问。rewrite则是把路径里的/api前缀去掉，因为很多后端接口本身没有/api这个 context-path。

很多人在这里第一反应是“我要不要配 rewrite”？答案是看后端。后端接口如果自带/api前缀，那 rewrite 就不要去掉/api，甚至可以直接不写 rewrite。后端如果只有/login、/user/list这种接口，前端统一走了/api前缀，那就必须 rewrite 掉。这个决定直接影响后面会不会 404，先有个印象，后面细说。

2. 常见代理报错的类型与根因

2.1 最经典的[vite] http proxy error

控制台出现类似下面的报错：

[vite] http proxy error: Error: connect ECONNREFUSED 127.0.0.1:8080 at TCPConnectWrap.afterConnect [as oncomplete] (net.js:...)

这是最基础也最容易定位的一类。ECONNREFUSED翻译过来就是“连接被拒绝”，说白了 vite 拿着你的配置去连目标地址，但目标地址根本没人在监听。常见原因就三个：后端服务没启动、端口写错、host 写错。

我见过最离谱的一次是同事把 target 写成了http://localhost:8080，但后端实际跑在http://127.0.0.1:8080的 IPv6 解析分支上，虽然大部分情况下 localhost 能正确解析到 127.0.0.1，但某些环境下会出现解析差异，尤其是后端同时监听了 IPv6 的::1时，反而会拒绝来自 IPv4 地址的请求。遇到 ECONNREFUSED，第一步不是改 vite 配置，而是先确认后端到底有没有起来、端口是多少。

2.2 代理“不生效”，请求全打到 dev server 返回 404

另一种常见现象是：控制台不报 proxy error，但浏览器 Network 面板里请求 URL 明明是http://localhost:5173/api/login，响应却是 vite 返回的index.html内容，状态码 404 或者干脆 200 但返回的是 HTML。

这种情况说明代理匹配根本没生效。vite 收到/api/login请求后，会在server.proxy里逐个匹配 key 的前缀，如果没匹配上，就会把请求交给 dev server 的静态资源处理逻辑，最终 fallback 到index.html。所以看到返回 HTML 而不是 JSON，基本可以断定代理规则没匹配上。

常见的匹配失败原因包括：配置文件里写的是'/api'，但请求路径是/api2/login这种前缀模糊的情况；或者请求路径根本没带/api，前端直接写的/login，而你代理规则只匹配/api；再比如改了配置但 dev server 没有重启成功。

2.3 WebSocket 代理连接失败

vite 的 HMR 本身就是 WebSocket 连接，如果你要代理的接口里包含 WebSocket 服务，比如/ws，只在 proxy 里写：

'/ws': { target: 'ws://localhost:3000' }

这时候浏览器会报：

WebSocket connection to 'ws://localhost:5173/ws' failed

这是因为 http-proxy 默认不会自动升级 WebSocket 连接，需要显式设置ws: true。不设置的情况下，代理层只做普通 HTTP 转发，握手阶段就会失败。这块在配置里经常被漏掉，特别是接手别人项目的时候，前后端接口联调都正常，唯独 WebSocket 死活连不上，十有八九就是这里的问题。

2.4 HTTPS 目标地址证书校验失败

如果代理目标是https://xxx.com，控制台可能会出现：

[vite] http proxy error: Error: unable to verify the first certificate

这是因为目标服务器用的是自签名证书，或者证书链不完整，而 http-proxy 默认会校验目标证书。开发阶段最简单的处理方式是在代理配置里加一行secure: false，告诉代理层“不要校验证书”。比如：

'/api': { target: 'https://api.example.com', changeOrigin: true, secure: false }

这块只建议在开发环境里这样处理。生产环境如果还走代理转发，证书校验还是要打开的，不然等于给自己埋雷。

问题现象速查表

3. 完整排查流程：从复现到修复

3.1 第一步：复现报错并把信息保存下来

有的人一看到报错就急着改 vite.config.ts，这是错误的打开方式。先复现，把控制台报错完整复制出来，同时打开浏览器 DevTools 的 Network 面板，看请求实际发到了哪个地址、响应状态码是什么、响应体是什么内容。

这里要区分两类报错：

• 浏览器 Console 里的Failed to fetch/ERR_CONNECTION_REFUSED，这类是浏览器直接层面的错误。
• vite 终端里的[vite] http proxy error，这类才是代理转发时报错。

两类信息结合起来看，基本就能判断问题出在哪一层。我曾经在一条报错上反复怀疑代理配置，结果仔细一看浏览器 Network 里请求根本没走 5173，而是被人写死了绝对地址http://localhost:8080/login，代理压根没参与。所以先看清楚请求到底发到哪儿了，再谈配置。

3.2 第二步：核对当前代理配置

把你正在用的 vite.config.ts 打开，照着下面几个问题逐项自查：

1. proxy key 前缀是不是真的覆盖了前端请求的路径？
2. target 的协议、host、端口是不是跟后端实际服务完全一致？
3. 后端接口自带前缀吗？如果带，rewrite 有没有误删前缀？
4. changeOrigin 设置没有？目标服务对 Host 有强校验吗？
5. 代理目标是不是 https？证书可信吗？
6. 请求里有没有 WebSocket？ws 开了吗？

依次确认完，基本能筛掉一半以上的问题。如果还没找到原因，进入下一步。

3.3 第三步：用 curl 验证后端接口本身可用

代理层只是“传话人”，如果后端接口本身挂了，代理再怎么配也是白搭。所以建议在终端里直接请求目标地址：

curl -v http://localhost:8080/api/login

看返回结果是 JSON、HTML 还是连接失败。如果 curl 都连不上，问题根本不在 vite，先解决后端服务。反过来，如果 curl 正常返回 JSON，但前端经代理就是报错，那问题基本锁定在 vite 代理配置这一层。

这一步能少走很多弯路。尤其多人协作项目里，后端分支切换、服务端口变化都是常事，指望同事每次都同步好再通知你，不如自己先 curl 一把。

3.4 第四步：启动 vite 的 debug 日志观察转发细节

标准排查到这里还定位不到，就启动 vite 的 debug 模式看转发过程：

npx vite --debug proxy

加了--debug proxy后，终端会输出和代理相关的详细日志，包括请求路径、命中规则、转发目标等。如果你是第一次看这些日志，不用慌，重点找这几类关键信息：

• 日志里显示的转发目标是不是你配置的 target？
• rewrite 之后的路径是否符合后端接口实际地址？
• 有没有在代理层就抛出的异常堆栈？

日志能直观地告诉你 vite 在转发时实际做了什么。很多你以为配置对了、实际没生效的地方，一旦看到日志就原形毕露了。有一次我明明写了 rewrite 把/api去掉，但日志显示转发路径里还是有/api，最后发现是配置文件里同时存在两段 proxy 配置，后面的把前面的覆盖了。这种东西靠肉眼检查很难发现，日志一照就出来了。

4. 代理配置的关键细节：changeOrigin、rewrite、ws 与 secure

4.1 changeOrigin 到底改了什么

很多人对changeOrigin的理解是“改了跨域来源”，这个说法对但不严谨。它实际改的是请求头里的Host字段。举例来说，你的前端跑在localhost:5173，代理转发时需要去请求localhost:8080，如果不设置 changeOrigin，请求头里的 Host 还是localhost:5173，后端拿到请求后如果对 Host 做校验（很多框架、网关、Nginx 反代都这么干），就会认为来源不合法。

设置changeOrigin: true之后，http-proxy 会把 Host 改成 target 的地址，也就是localhost:8080，后端看起来就像浏览器在直接访问它一样。用大白话讲，你拜托同事替你带话给另一个人，结果同事递名片的时候报了你的名字，对方不认；changeOrigin 就是让你同事递名片时报他自己的名字，对方才愿意听。

4.2 rewrite 是双刃剑，写错方向就是无底洞

rewrite参数是一个函数，接收原始路径，返回新路径。最常见的写法是：

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

这里的正则^\/api表示“只匹配开头的/api”，替换成空字符串。这样/api/user/list就变成了/user/list。

坑点在于：如果你要保留/api前缀，就不要写这个 rewrite；如果你要删除前缀，必须注意正则是^\/api，而不是/api，更不是'api'。写path.replace('/api', '')和写path.replace(/\/api/, '')的差别很大，前者是替换第一个出现的/api，后者同样也是替换第一个，但如果没有^限定，一旦路径里出现了第二个/api，也可能被误伤。

另外要提醒一句：target 的地址里不要也带路径。比如你写target: 'http://localhost:8080/api'，然后又写了rewrite: (path) => path.replace(/^\/api/, '')，最终转发出去的路径可能就是/api+/login这种叠加态，非常容易出错。我的建议是 target 只写协议 + host + 端口，路径全部交给 rewrite 控制。这样路径规则只有一个地方维护，出问题也好排查。

4.3 ws、secure、changeOrigin 的组合

这三个参数经常一起出现在配置里，它们分别管三件不同的事：

• ws: true——让代理支持 WebSocket 升级；
• secure: false——跳过目标证书校验，用于自签名 https 的开发场景；
• changeOrigin: true——改写 Host 头。

一个典型的 HTTPS + WebSocket 代理配置：

'/api': { target: 'https://api.example.com', changeOrigin: true, secure: false }, '/ws': { target: 'ws://api.example.com', ws: true, changeOrigin: true, secure: false }

需要留意的是，WebSocket 代理的 target 协议通常要写成ws://或wss://，而不是http://。你写http://它也能工作，但语义上不明确，出问题的时候容易看晕。而且有些后端服务对 upgrade 请求头敏感，target 协议不对会导致握手一直被拒绝。

4.4 base 配置和代理的关系

项目的base配置经常会被误以为是代理的一部分。实际上 base 控制的是构建后静态资源的公共路径前缀，比如部署到https://xxx.com/subdir/，base 就设成/subdir/。它和开发环境接口代理没有直接关系，但如果 base 设置得太特殊，比如/api/，开发时静态资源请求会被代理规则误拦截，导致页面样式加载不出来。

这种情况我踩过一次：为了部署子路径，把 base 设成了/api/，结果 vite 启动后页面所有 js、css 请求都带上了/api前缀，代理规则直接把这些资源请求转发到了后端，页面白屏，控制台全是 MIME type 错误。后面把 base 改为独立的子路径前缀、代理规则也做了区分，问题才解决。所以如果你的页面里资源路径和接口路径共用同一套前缀，代理规则要格外小心。

5. 实战排查案例复盘

5.1 案例一：接口全部 404，问题出在 rewrite 的正则范围

某次项目里前端统一请求路径带/api，但后端接口没有这个前缀，所以按预期应该用 rewrite 去掉/api。我当时写成了：

'/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace('/api', '') }

看起来能跑，请求/api/login变成/login。但有一个特殊接口是/api/v2/agent/api/list，rewrite 之后变成了/v2/agent/api/list，路径里第二个/api被保留了，而后端这个接口实际路径是/v2/agent/list，结果这个接口始终 404。

排查到最后才发现 rewrite 逻辑应该用^\/api限定只删前缀：

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

改成这样之后/api/v2/agent/api/list就正确变成了/v2/agent/api/list（对这个后端来说路径确实是这样的，因为它的第二个/api是接口本身的组成部分）。这个案例想说明的是：rewrite 一定要想清楚“我要删的是这个前缀，不是所有同名片段”，正则的锚点^是在这里保命的。

5.2 案例二：ECONNREFUSED，不是代理的锅

另一个项目，后端告诉我服务跑在 3000 端口，我配好了代理，结果启动后所有接口全部报ECONNREFUSED 127.0.0.1:3000。我当时第一反应是改 changeOrigin，又试了调整 target 写法，都没用。

冷静下来后直接在终端执行：

curl http://localhost:3000/health

结果也是连接失败。跑到后端同事那一看，服务确实起来了，但监听的是 3001 端口，他心里的“3000”是 IDE 里默认的配置，实际运行参数是 3001。改完 target 端口后一切正常。

这个案例特别想分享给所有遇到代理报错的人：先确认“目标服务真的可达”这件事本身，再回来看代理配置。很多时候你折腾半天代理，其实是后端服务地址变了、或者压根没起来。

5.3 案例三：改了 vite.config.ts 但代理不生效

还有一次，配置看起来一点问题没有：

'/api': { target: 'http://localhost:8080', changeOrigin: true }

但前端请求/api/login后始终返回 index.html，说明代理没匹配上。我开始怀疑配置格式，又怀疑 vite 版本，折腾一圈后突然反应过来：vite.config.ts 里的代码写了两段 server 配置，前一个文件被后面的同名配置覆盖了。

其实 Vite 对配置文件有比较智能的热重载机制，正常情况下修改 vite.config.ts 会自动重启 dev server。但如果你的配置文件本身逻辑复杂，或者有多个环境文件互相覆盖，很可能你改的那个文件压根没有被实际加载。建议在配置里临时加一行console.log('proxy config loaded')，看终端有没有输出。没有输出，就说明你改的文件根本不在生效路径上。

6. 如何快速判断代理是否生效

6.1 Network 面板里的三个关键信息

打开 DevTools 的 Network 面板，筛选你要调试的接口请求，看三样东西：

1. 请求 URL 的域名和端口是不是localhost:5173。
2. 响应体是 JSON 还是 HTML。
3. 响应状态码是多少。

如果请求 URL 是localhost:5173，响应体是 JSON，状态码正常，说明代理已经生效。如果响应体是 HTML，代理大概率没匹配上，请求被 vite 当静态资源处理了。

这里有个更直观的验证方法：临时把 target 指向一个公开的测试服务，比如https://httpbin.org/anything，这个服务会把收到的请求信息原样返回。这样你就能在响应里直接看到最终转发出去的完整路径、Host、Query 参数等，帮助我们判断 rewrite 和 changeOrigin 是否真的按预期工作。

6.2 用 proxy 的 configure 钩子打印转发细节

Vite 的代理配置支持configure函数，可以在代理实例上监听事件。比如：

'/api': { target: 'http://localhost:8080', changeOrigin: true, configure(proxy) { proxy.on('proxyReq', (proxyReq) => { console.log('proxyReq:', proxyReq.path) }) proxy.on('proxyRes', (proxyRes) => { console.log('proxyRes status:', proxyRes.statusCode) }) } }

这样每次代理转发请求、收到响应，终端都会打印对应的日志。通过这个输出，你可以明确看到“vite 实际转发出去的路径”到底长什么样。很多时候你以为 rewrite 生效了，其实没有；你以为 target 是对的，其实路径拼接出了问题。configure 里的日志就是你判断这些问题的最后依据。

不过要注意，configure 只对配置里挂载的代理实例生效，如果你的项目用了两套代理配置，要分别加监听才能看清各自的行为。

7. 常见问题速查表与避坑清单

7.1 问题速查表

7.2 避坑清单

• target 只写协议 + host + 端口，不要带路径，路径交给 rewrite 统一管理。
• rewrite 正则必须加^锚点，只删掉开头的路径前缀。
• 改了 vite.config.ts 不生效时，先确认改的文件是不是实际加载的配置文件。
• 代理报错别急着改代理，先用 curl 验证后端接口本身通不通。
• 代理只对 dev server 生效，生产环境的代理要交给 Nginx 等网关层去处理。
• WebSocket 代理一定要ws: true，不要用 HTTP 代理配置硬套。
• 如果 target 是 https 且开发环境证书不可信，记得secure: false，但生产环境不要学。
• base 配置和代理配置不要共用同一套敏感前缀，否则静态资源容易被误转发。

我自己在这个坑里进进出出很多次，最大的体会是：报错本身不可怕，可怕的是不看日志、不验证后端、就埋头猜配置。vite 的代理机制其实很透明，只要请求链路链路里的每一段都验证一遍，问题一定能定位到。毕竟代理层的坑翻来覆去就那么几个：目标不可达、路径写错、Host 校验失败、WebSocket 没开、证书不认。把这几项逐个排除，剩下的基本就是小问题了。