Vue3 Vite本地启动如何将localhost改为IP地址访问？

Question

在 Vue3 + Vite 项目本地开发时，执行 `npm run dev` 默认仅监听 `localhost:5173`，导致同一局域网内其他设备（如手机、平板或同事电脑）无法通过本机 IP（如 `http://192.168.1.100:5173`）访问应用，出现连接拒绝或空白页。常见原因包括：Vite 开发服务器默认绑定 `localhost`（即 `127.0.0.1`），不对外网开放；防火墙或路由器限制端口访问；未正确配置 `vite.config.ts` 中的 `server.host` 和 `server.port`；或未处理跨域与热更新 WebSocket 地址（`ws://localhost:5173/...`）导致 HMR 失败。此外，部分网络环境（如公司内网、Docker 容器）还涉及代理、IPv6 优先或 `host` 解析异常等问题。如何安全、可靠地让 Vite 开发服务器支持局域网 IP 访问，并确保资源加载、热更新和 Source Map 正常工作，是前端开发者高频遇到的调试痛点。

Answer 1

```html

一、现象定位：从“连不上”到“连上了但白屏/热更新失效”

执行 npm run dev 后，Vite 默认仅绑定 127.0.0.1:5173，局域网设备访问 http://192.168.1.100:5173 时出现 ERR_CONNECTION_REFUSED 或空白页（控制台报 Failed to load resource: net::ERR_FAILED）。根本原因并非单纯“端口没开”，而是 Vite 的开发服务器、资源路径、HMR WebSocket 地址三者未协同对齐。

二、核心机制剖析：Vite 开发服务器的三层网络契约

• HTTP Server 绑定层：决定监听哪个 IP 和端口（server.host/server.port）
• 资源路径生成层：影响 <script src>、import.meta.url、Source Map URL 等绝对路径（受 base 和 server.origin 控制）
• HMR 通信层：WebSocket 连接地址由客户端自动推导，若推导为 ws://localhost:5173 则跨设备必然失败（需显式指定 server.hmr.overlay + server.hmr.clientPort）

三、安全配置方案：渐进式启用局域网访问

配置项	推荐值	说明
server.host	"0.0.0.0" 或 true	允许所有 IPv4 接口监听；生产环境禁用
server.port	5173（可选自定义）	避免与公司代理/防火墙策略冲突
server.origin	"http://192.168.1.100:5173"	强制资源路径、Source Map URL、import.meta.env.BASE_URL 基于此生成
server.hmr.port	5173	复用 HTTP 端口，避免额外开放端口
server.hmr.https	false	局域网无需 HTTPS；若强制开启需配证书且手机需信任

四、典型 vite.config.ts 安全配置示例

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// 自动获取本机局域网 IPv4 地址（规避 IPv6 优先问题）
const getLocalIp = (): string => {
  const interfaces = require('os').networkInterfaces()
  for (const dev in interfaces) {
    for (const iface of interfaces[dev]) {
      if (iface.family === 'IPv4' && !iface.internal) return iface.address
    }
  }
  return '127.0.0.1'
}

const LOCAL_IP = getLocalIp()

export default defineConfig({
  plugins: [vue()],
  server: {
    host: '0.0.0.0', // ✅ 允许外部访问
    port: 5173,
    strictPort: true,
    origin: `http://${LOCAL_IP}:5173`, // ✅ 关键！统一资源基址
    hmr: {
      overlay: true,
      clientPort: 5173, // ✅ 强制 HMR 使用同端口 WebSocket
      protocol: 'ws'
    }
  },
  resolve: {
    alias: {
      '@': '/src'
    }
  }
})

五、网络环境适配矩阵

graph TD A[局域网访问失败] --> B{网络环境类型} B -->|标准家庭/办公 Wi-Fi| C[检查防火墙入站规则
Windows：启用“专用网络”
macOS：确认“防火墙选项”中允许 5173] B -->|公司内网/代理环境| D[确认 IT 策略是否封禁非标端口
尝试改用 8080/3000 等常用端口] B -->|Docker 容器开发| E[启动命令加 --host 0.0.0.0
容器映射 -p 5173:5173
确保宿主机 network_mode: host] B -->|IPv6 优先系统| F[在 vite.config.ts 中显式指定 IPv4 地址
禁用 os.networkInterfaces() 的 IPv6 分支]

六、调试验证清单（逐项打钩）

1. ✅ 手机浏览器访问 http://192.168.1.100:5173 显示 Vue 页面
2. ✅ 浏览器开发者工具 Network 标签中，所有 JS/CSS/Source Map 请求状态码为 200，URL 均以 http://192.168.1.100:5173/ 开头
3. ✅ 修改 src/App.vue 后，手机页面自动刷新（非手动 F5）
4. ✅ 控制台无 WebSocket connection to 'ws://localhost:5173/' failed 报错
5. ✅ Source Map 可点击跳转至原始 .vue 文件（Chrome DevTools → Sources → webpack:// → ./src/）

七、高阶防护：企业级开发环境加固建议

对于金融、政务等强合规场景，建议在 vite.config.ts 中增加：
• 使用 server.watch.ignored 排除 node_modules/.git 等敏感目录监听；
• 通过 process.env.NODE_ENV === 'development' 动态启用 server.host，CI/CD 中强制 host: 'localhost'；
• 集成 vite-plugin-visualizer 监控包体积，避免因大资源阻塞局域网传输；
• 在 package.json 的 scripts.dev 中添加预检脚本：node -e "require('./scripts/check-network.js')"，自动校验防火墙状态与端口占用。

```