前端工程化 / 系统课时
配置 HTTP 与 WebSocket 代理
配置 HTTP 与 WebSocket 代理
本课把浏览器发往 Vite 开发服务器的接口与 WebSocket 请求转发到不同上游,并通过事件日志观察请求路径、响应状态和连接异常。完成后,你能同时配置 HTTP 与 WebSocket 代理,并按链路快速定位 404、连接拒绝和握手失败。
学习目标
- 理解代理匹配、路径改写和上游目标之间的关系
- 配置 HTTP 接口与 WebSocket 两类代理规则
- 使用代理事件和客户端验证结果定位转发故障
先看请求如何被转发
Vite 的 server.proxy 使用“匹配前缀到代理选项”的对象。请求一旦命中代理规则,就会直接交给代理处理,不再按普通 Vite 资源请求转换;configure 可访问代理实例并监听事件。:contentReference[oaicite:5]{index=5}

浏览器只需要访问 Vite 的地址。target 决定上游服务器,changeOrigin 让代理请求使用目标主机的 Host,rewrite 只修改转发路径,ws: true 则允许处理 WebSocket Upgrade。路径是否改写必须以真实后端路由为准,不能机械删除前缀。
编写代理配置
下面的配置把 /api/health 转为上游的 /health,把 /socket/chat 转为 WebSocket 上游的 /ws/chat,并分别记录 HTTP 与 WebSocket 事件:
import { defineConfig } from 'vite'
export default defineConfig({
server: {
port: 5173,
strictPort: true,
proxy: {
'/api': {
target: 'http://127.0.0.1:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, ''),
configure(proxy) {
proxy.on('proxyReq', (proxyReq, req) => {
console.log(
`[HTTP ->] ${req.method} ${req.url} host=${proxyReq.getHeader('host')}`,
)
})
proxy.on('proxyRes', (proxyRes, req) => {
console.log(`[HTTP <-] ${proxyRes.statusCode} ${req.url}`)
})
proxy.on('error', (error, req) => {
console.error(`[HTTP !!] ${req.url}`, error.message)
})
},
},
'/socket': {
target: 'ws://127.0.0.1:8081',
ws: true,
changeOrigin: true,
rewrite: (path) => path.replace(/^\/socket/, '/ws'),
configure(proxy) {
proxy.on('open', () => console.log('[WS] upstream opened'))
proxy.on('close', () => console.log('[WS] upstream closed'))
proxy.on('error', (error) => {
console.error('[WS !!]', error.message)
})
},
},
},
},
})Vite 官方示例同样通过 configure 监听 error、proxyReq 和 proxyRes,并支持在代理规则中使用 changeOrigin 与 rewrite。:contentReference[oaicite:6]{index=6}
启动并验证 HTTP 代理
先确保两个上游服务已经监听对应端口,再启动 Vite:
npm run dev预期输出
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:5173/假设上游 http://127.0.0.1:8080/health 存在且返回 200,可从 Vite 入口验证;实际项目应把 /health 替换成真实接口:
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:5173/api/health预期输出
200同时,Vite 终端应出现与本次请求对应的事件:
[HTTP ->] GET /api/health host=127.0.0.1:8080
[HTTP <-] 200 /api/health若前端收到 404,但日志已经出现 [HTTP <-] 404,说明请求已到达上游,应检查 rewrite 后的路径和后端路由,而不是继续修改浏览器端 CORS 设置。
验证 WebSocket 代理
在已打开的 Vite 页面控制台执行以下代码。它会根据页面协议自动选择 ws 或 wss;HTTPS 页面应连接 wss://当前 Vite 地址/socket,避免浏览器混合内容限制。:contentReference[oaicite:7]{index=7}
const scheme = location.protocol === 'https:' ? 'wss' : 'ws'
const socket = new WebSocket(`${scheme}://${location.host}/socket`)
socket.addEventListener('open', () => console.log('ws open'))
socket.addEventListener('message', (event) => {
console.log('ws message', event.data)
})
socket.addEventListener('close', (event) => {
console.log('ws close', event.code)
})
socket.addEventListener('error', () => console.error('ws error'))预期输出
ws openVite 终端还应输出 [WS] upstream opened。若客户端立即出现 ws error,先确认请求路径命中 /socket,再检查 ws: true、上游端口和上游是否接受改写后的 /ws 路径。
按日志定位常见故障
| 现象 | 优先检查 |
|---|---|
ECONNREFUSED 或 502 |
target 主机、端口、上游进程是否启动 |
| 上游返回 404 | rewrite 后的实际路径与后端路由 |
| HTTP 正常但 WebSocket 失败 | ws: true、Upgrade 请求、WebSocket 上游路径 |
HTTPS 页面直连 ws:// 失败 |
改为连接 Vite 的 wss:// 同源地址 |
| 请求没有任何代理日志 | 浏览器路径未命中代理键,或请求发到了其他端口 |
| Host 路由到错误服务 | 检查是否需要 changeOrigin: true |
事件日志用于定位链路,不应长期打印令牌、Cookie、完整查询参数或消息正文。只记录方法、路径、状态码和必要的连接错误,避免把敏感数据写入终端与 CI 日志。
代理的边界
server.proxy 只作用于 Vite 开发服务器,不会自动进入生产构建产物。部署时必须在 Nginx、网关、云平台或应用服务器中重新配置等价路由。前端代码应尽量保留 /api 和 /socket 这类相对路径,避免把开发机地址写死到业务代码中。