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 的解析歧义，让本地开发环境稳定恢复。
