前端工程化 / 系统课时
配置 host 与端口
配置 host 与端口
本课解决 Vite 开发服务器“本机能开、其他设备却访问不到”以及端口被占用后自动漂移的问题。完成配置后,你将得到一个监听范围明确、端口固定,并能在局域网、容器或 WSL 场景中稳定验证的开发服务。
学习目标
- 理解
host决定监听地址,而不是访问域名 - 使用
port与strictPort固定开发端口 - 按局域网、Docker 和 WSL 的网络边界定位访问失败
先判断监听范围
Vite 默认把 server.host 设为 localhost,适合仅在当前电脑访问。设为 true 或 0.0.0.0 后,服务会监听全部可用地址,终端通常会同时显示本机地址和局域网地址。监听全部地址会扩大可访问范围,因此还要配合防火墙与主机白名单。:contentReference[oaicite:0]{index=0}

写入稳定配置
在项目根目录创建或修改 vite.config.ts。下面的配置适合端口被代理规则、移动端调试地址或容器映射固定引用的项目。
import { defineConfig } from 'vite'
export default defineConfig({
server: {
// 监听全部网络接口,允许局域网或容器映射后的请求进入
host: true,
port: 5173,
// 端口被占用时直接失败,避免悄悄切换到 5174
strictPort: true,
},
})port 的默认值是 5173;未启用 strictPort 时,如果该端口已被占用,Vite 会继续尝试下一个可用端口。启用后,端口冲突会让启动失败,便于脚本、反向代理和回调地址及时发现配置不一致。:contentReference[oaicite:1]{index=1}
启动并验证地址
运行项目已有的开发脚本:
npm run dev预期输出:
VITE v<VERSION> ready in <TIME> ms
➜ Local: http://localhost:5173/
➜ Network: http://<LAN_IP>:5173/版本、耗时和局域网 IP 会因环境不同而变化。当前电脑先访问 Local 地址;同一网络中的手机或另一台电脑应访问 Network 地址。若终端没有显示网络地址,先确认 host 配置是否被其他模式配置或命令行参数覆盖。
处理局域网、容器与 WSL 边界
局域网访问需要同时满足三项条件:Vite 监听非回环地址、操作系统防火墙允许入站端口、客户端能路由到主机的局域网 IP。仅把 host 改为 true,不会自动修改防火墙或路由。
Docker 中还必须发布容器端口,例如宿主机端口与容器内 Vite 端口都使用 5173 时,需要建立 5173:5173 映射;未发布的容器端口默认不能从宿主机外部直接访问。:contentReference[oaicite:2]{index=2}
WSL2 默认存在虚拟网络边界,Vite 官方也明确说明仅设置 host: true 不足以保证从局域网访问。应继续检查 Windows 防火墙、WSL 网络模式,必要时配置端口转发;Windows 主机本地访问与局域网其他设备访问不是同一条链路。:contentReference[oaicite:3]{index=3}
端口占用时的定位顺序
先阅读启动错误,确认冲突端口;再判断占用进程是否可以停止;不能停止时,统一修改 Vite 端口以及代理、容器映射、测试脚本和回调地址。不要仅关闭 strictPort 让 Vite 自动换端口,否则浏览器可能能打开页面,但依赖固定端口的 HMR、代理或自动化测试仍会失败。