在 apache 中代理 vue3 vite 开发服务器的 websocket 连接,核心做法是启用 mod_proxy、mod_proxy_http 和 mod_proxy_wstunnel 模块,并在虚拟主机配置中使用 proxypass 和 proxypassreverse 指令将请求转发到本地 vite 服务(默认端口 5173)。这样做能让浏览器通过标准的 http/https 协议与 vite 建立 websocket 连接,从而支持热更新(hmr)功能。如果未正确配置 mod_proxy_wstunnel,websocket 握手会失败,导致页面无法自动刷新。

Apache 需要哪些模块来支持 WebSocket 代理
必须启用 mod_proxy、mod_proxy_http 和 mod_proxy_wstunnel 三个模块。缺少 mod_proxy_wstunnel 会导致 WebSocket 升级请求被拒绝或回退为普通 HTTP 请求,从而中断 HMR 连接。

<VirtualHost *:80>
ServerName vue-app.local
# 启用必要的代理模块
ProxyPreserveHost On
# 代理所有 HTTP 请求到 Vite 开发服务器
ProxyPass / http://localhost:5173/
ProxyPassReverse / http://localhost:5173/
# 代理 WebSocket 连接到 Vite 开发服务器
# 注意:路径需与 Vite 配置的 ws.path 一致,默认为 /
ProxyPass /ws ws://localhost:5173/ws
ProxyPassReverse /ws ws://localhost:5173/ws
</VirtualHost>上述配置中,ProxyPass / 处理静态资源和常规 API 请求,而 ProxyPass /ws 专门处理 WebSocket 流量。Vite 默认使用根路径 / 进行 WebSocket 通信,因此通常只需代理根路径即可。若 Vite 配置了自定义 server.ws.path,则需相应调整 ProxyPass 的路径匹配规则。
立即学习“前端免费学习笔记(深入)”;
如何验证 WebSocket 代理是否生效
通过检查浏览器开发者工具的 Network 面板,确认 WebSocket 连接状态为 101 Switching Protocols,且无跨域或连接错误。同时,修改 Vue 组件代码后,页面应能即时刷新,表明 HMR 通道正常。

# 在终端中启动 Vite 开发服务器 npm run dev # 访问 Apache 托管的站点 http://vue-app.local
当你在浏览器中打开 http://vue-app.local 时,Apache 会将请求转发至 localhost:5173。此时,浏览器发起的 WebSocket 连接会被 mod_proxy_wstunnel 拦截并隧道式转发至 Vite 服务器。你可以在 Chrome DevTools 的 Console 中看到类似 [vite] connected. 的日志,这表示 WebSocket 已成功建立。若出现 ERR_CONNECTION_REFUSED 或 404 错误,请检查 Apache 错误日志中是否有 proxy:error 相关记录,并确认 Vite 服务正在运行且端口未被占用。
Vite 配置中的 server.host 对代理有何影响
当 Vite 的 server.host 设置为 '0.0.0.0' 或 true 时,Vite 会监听所有网络接口,允许 Apache 所在机器的其他进程(包括 Apache 本身)通过 localhost 访问。若设置为 'localhost',则仅绑定本地回环地址,同样可被 Apache 代理。但若设置为特定 IP 或域名,可能导致 Apache 无法通过 localhost:5173 连接到 Vite,从而引发代理失败。


















