vite项目开发环境启动白屏

Vite 启动成功但页面打不开：加上 host: '127.0.0.1' 就恢复了，为什么？

今天开发时遇到一个比较"迷惑"的问题：

• 终端里 npm run dev 正常启动
• Vite 提示 ready in xxx ms
• 控制台没有报错
• 但浏览器访问 http://localhost:1111/ 时，直接报：

ERR_CONNECTION_REFUSED

最后只是在 vite.config.ts 里加了这段配置，问题就解决了：

server: {
  host: '127.0.0.1', //新加了host
  port: 1111,
},

那为什么加了 host: '127.0.0.1' 就好了？这篇文章把这次问题的现象、原因和解决方案整理一下。

---

一、问题现象

项目使用 Vite，本地启动命令：npm run dev

终端输出类似这样：

VITE v7.x.x ready in 504 ms

➜ Local: http://localhost:1111/

看起来一切正常，但浏览器打开后却提示：

无法访问此网站 localhost 拒绝了我们的连接请求 ERR_CONNECTION_REFUSED

最关键的是：

• 页面打不开
• 控制台没有报错
• 代码本身看起来也没问题

这种情况特别容易让人误以为是 Vue 组件、入口文件或者业务代码出了问题，但实际上这次并不是前端逻辑问题，而是 开发服务器的监听地址问题。

---

二、这次问题的根因

这次问题的根因可以概括成一句话：

Vite 默认监听的地址，与我当前机器上 localhost 的实际解析/访问方式不一致，导致浏览器访问被拒绝。

更具体一点说，就是：

1. localhost 不一定只等于 127.0.0.1

很多人会默认认为：

localhost = 127.0.0.1

但实际上不是。

在现代操作系统里，localhost 往往可能同时解析到：

• 127.0.0.1（IPv4）
• ::1（IPv6）

有些环境会优先走 IPv6，也就是 ::1。

---

2. Vite 启动了，不代表浏览器一定能访问成功

Vite 终端里显示 ready，只能说明：

• Node 进程起来了
• Vite 逻辑开始监听某个地址和端口了

但这不等于：

• 浏览器一定能通过你输入的 URL 成功连上它

如果服务绑定在 IPv6 地址、而浏览器/系统/代理最终没有按同样方式访问，或者本机网络栈对 localhost 的处理存在差异，就可能出现：

• 终端显示启动成功
• 浏览器却连不上
• 并且前端控制台没有任何 JS 报错

因为这时候问题发生在 网络连接阶段，还没走到页面脚本执行。

---

3. 这次加 host: '127.0.0.1' 后生效，本质上是"强制固定到 IPv4"

当我加上：

server: {
  host: '127.0.0.1',
  port: 1111,
},

实际效果是：

• Vite 明确绑定到 127.0.0.1
• 浏览器也直接通过 IPv4 地址访问本地服务
• 避开了 localhost 在本机环境下的 IPv4 / IPv6 解析歧义

也就是说，这个配置的本质不是"让 Vite 更快"或者"修复了业务代码"，而是：

把本地开发服务器的监听地址，从模糊的 localhost，改成了明确的 127.0.0.1。

---

三、为什么之前会报 ERR_CONNECTION_REFUSED，但控制台没有错误？

这是这类问题最容易误导人的地方。

原因很简单：

浏览器控制台通常显示的是 页面加载后的脚本错误，比如：

• JS 语法错误
• Vue 运行时错误
• 接口报错
• 资源加载失败

但这次浏览器连页面都没连上，所以根本没有机会执行前端代码。

也就是说：

• 不是页面渲染报错
• 不是组件逻辑报错
• 不是业务代码报错
• 而是浏览器在"建立连接"这一步就失败了**

所以最终看到的是：

ERR_CONNECTION_REFUSED

而不是前端控制台里的红色报错堆栈。

---

四、最终解决方案

修改前

server: {
  port: 1111,
},

修改后

server: {
  host: '127.0.0.1',
  port: 1111,
},

修改完成后，重新启动：

npm run dev

然后直接访问：

http://127.0.0.1:1111/

页面恢复正常。

---

五、为什么 host: '127.0.0.1' 能解决问题？

可以直接理解成下面这张逻辑链：

没加 host 时

• Vite 使用默认 host
• localhost 在系统里可能优先解析到 IPv6（::1）
• 浏览器访问 localhost 时，和服务实际监听地址不完全一致
• 最终连接失败

加了 host: '127.0.0.1' 后

• Vite 明确监听 IPv4 地址 127.0.0.1
• 浏览器也直接访问 127.0.0.1
• 服务监听地址和访问地址完全一致
• 连接恢复正常

一句话总结：

不是 Vite 没启动，而是"启动后的监听地址"与"浏览器访问地址"之间存在偏差。

---

六、遇到这类问题怎么排查？

如果你也遇到：

• Vite 显示启动成功
• 页面却打不开
• 控制台没有报错

可以按下面顺序排查。

1. 先判断是不是"代码错误"

如果是代码错误，通常会出现：

• 浏览器白屏但能打开页面
• 控制台有 JS 报错
• 网络面板能看到 index.html / main.ts 已经加载

如果是这类情况，就查业务代码。

---

2. 如果直接 ERR_CONNECTION_REFUSED

那优先怀疑：

• 本地端口没真正可访问
• localhost 解析有问题
• IPv4 / IPv6 监听不一致
• 被系统代理、VPN、防火墙影响

这种情况通常不是组件代码问题，而是 开发服务器访问路径问题。

---

3. 直接指定 host

最直接有效的办法：

server: {
  host: '127.0.0.1',
  port: 1111,
},

如果你需要局域网访问，可以改成：

server: {
  host: true,
  port: 1111,
},

或者：

server: {
  host: '0.0.0.0',
  port: 1111,
},

---

七、我的结论

这次问题本质上不是"项目没跑起来"，而是：

Vite 在本机环境中使用默认监听地址时，和浏览器访问 localhost 的方式不一致，导致连接被拒绝。

最终通过显式指定：

host: '127.0.0.1'

强制 Vite 使用 IPv4 回环地址，解决了本地 localhost / IPv6 解析带来的歧义问题。

---

八、一段适合直接放文章结尾的总结

如果你遇到 Vite 启动成功但浏览器打不开、控制台也没有报错 的情况，不要先怀疑 Vue 代码本身，优先检查开发服务器的监听地址。

在某些 Windows 或本机网络环境下，localhost 可能会涉及 IPv4 / IPv6 的解析差异，导致：

• Vite 看起来已经启动
• 浏览器却无法建立连接

这时候可以直接在 vite.config.ts 中指定：

server: {
  host: '127.0.0.1',
  port: 1111,
},

这样可以绕开 localhost 的解析歧义，让本地开发环境稳定恢复。