localhost 访问异常排查笔记

localhost 访问异常排查笔记

背景场景

本地跑 npm run dev（vite），手机通过局域网 IP 能正常访问 H5 页面，但 PC 浏览器访问 http://localhost:端口 报错（如 ERR_HTTP_RESPONSE_CODE_FAILURE）。

---

核心知识点：localhost 和 127.0.0.1 不是完全一样的

• 127.0.0.1：IPv4 回环地址，唯一、明确
• localhost ：是一个域名，系统解析时可能指向 127.0.0.1（IPv4）或 ::1（IPv6）。现代系统（尤其是 Windows + Chrome 组合）通常优先走 IPv6

为什么会踩坑

如果电脑上有旧的/残留的进程 占用了同一端口的 IPv6 地址（::1:端口），而新启动的服务虽然也监听了这个端口，系统仍可能把 localhost 优先解析到那个卡住的旧进程上，导致：

• 用 IP 地址（127.0.0.1 或局域网 IP）访问 → 正常
• 用 localhost 访问 → 报错（连接到了状态异常的旧进程）

---

排查步骤

1. 查端口占用情况（Windows）

netstat -ano | findstr 端口号

关注点：同一个端口是否出现两个不同的 PID

正常情况应该只有一组 PID，类似：

TCP    0.0.0.0:5173     0.0.0.0:0    LISTENING    27148
TCP    [::]:5173        [::]:0       LISTENING    27148

如果出现这种情况，说明有旧进程残留：

TCP    [::1]:5173       [::]:0       LISTENING    7360   ← 单独占了 IPv6 loopback 的旧进程

2. 定位到具体是哪个进程

tasklist | findstr 7360

确认这个 PID 是不是之前忘记关掉的旧 vite 进程。

---

解决办法

临时方案（当下能用就行）：

直接改用 http://127.0.0.1:端口/ 访问，绕开 IPv6 解析问题。

根治方案：

taskkill /PID 旧进程ID /F

杀掉残留的旧进程，释放端口，之后 localhost 也能正常访问。

---

什么时候容易踩到

• 用 VS Code 集成终端反复开关多个终端窗口跑 npm run dev，容易忘记关掉旧的
• 切换分支 / 改完 vite.config.ts 或 .env 文件后重启服务，没有先确认旧进程真的退出

顺带提醒

vite.config.ts 和 .env.development / .env.production 这类配置文件的修改，vite 不会自动热更新 ，必须手动 Ctrl+C 停掉后重新 npm run dev 才会生效。