curl http://localhost:5173 返回 Connection refused，如何排查？

Question

`curl http://localhost:5173` 返回 `Connection refused`，表明本地 5173 端口无服务监听。常见原因：① 前端开发服务器（如 Vite、Vue CLI）未启动；② 启动后因错误自动退出（检查控制台报错或 `npm run dev` 是否仍在运行）；③ 端口被占用或配置变更（如 `.env` 中 `VITE_PORT=3000` 覆盖了默认 5173）；④ 绑定地址非 `localhost`（如 `--host 0.0.0.0` 但未配 `--port 5173`，或启用了 HTTPS 重定向）；⑤ 防火墙/代理干扰（较少见，但 Docker 或 WSL 环境需注意网络模式）。排查步骤：先 `lsof -i :5173`（macOS/Linux）或 `netstat -ano | findstr :5173`（Windows）确认端口空闲；再 `ps aux | grep vite` 检查进程是否存在；最后查看项目启动日志中是否成功打印 `Local: http://localhost:5173/`。切忌仅依赖浏览器访问——curl 是更底层的验证手段。

Answer 1

```html

一、现象层：curl 返回 Connection refused 的本质含义

curl http://localhost:5173 返回 Connection refused 并非前端渲染失败，而是 TCP 连接在三次握手阶段即被内核拒绝——目标端口上无任何进程处于 LISTEN 状态。这与 HTTP 404、502 或 CORS 错误有根本性区别：它发生在网络协议栈的传输层（OSI Layer 4），早于应用层（Layer 7）的任何响应逻辑。因此，问题必定位在服务未启动、启动失败或监听配置异常三类根因中。

二、进程层：验证服务是否真实存活

• macOS/Linux：lsof -i :5173 —— 若无输出，说明端口未被监听；若有输出但 PID 不属于 Vite/Vue CLI，则为端口劫持
• Windows：netstat -ano | findstr :5173 + tasklist /FI "PID eq XXXX" 双步确认进程归属
• 补充命令：ps aux | grep -E "(vite|vite-dev-server|vue-cli-service)" | grep -v grep 排除僵尸进程干扰

⚠️ 注意：npm run dev 进程看似运行中，但若其子进程（如 esbuild、rollup）崩溃，主进程可能静默退出——需用 pgrep -f "vite dev" 而非仅看终端光标是否闪烁。

三、配置层：环境变量与启动参数的隐式覆盖

配置文件/位置	关键键名	典型值示例	影响范围
.env	VITE_PORT=3000	强制覆盖默认 5173	全量 Vite 应用
vite.config.ts	server.port: 8080	代码级硬编码	仅当前项目
package.json	"dev": "vite --port 4173"	CLI 参数优先级最高	单次执行

四、网络层：绑定地址与跨环境访问的陷阱

当使用 vite --host 0.0.0.0 启动时，Vite 默认仍监听 127.0.0.1:5173（仅本地回环），而 --host 0.0.0.0 实际要求显式声明 --port 5173 并确保 server.host 设为 "0.0.0.0"。在 WSL2 中更需注意：
- Windows 主机访问 http://localhost:5173 实际走的是 WSL2 的 NAT 映射
- 但 curl 在 WSL2 内部执行时，localhost 指向 WSL2 自身而非 Windows —— 此时若服务未在 WSL2 中启动，必然 Connection refused

五、纵深防御：构建可复现的诊断流水线

#!/bin/bash
# 一键诊断脚本（Linux/macOS）
PORT=5173
echo "=== Step 1: Port status ==="
lsof -i :$PORT 2>/dev/null || echo "❌ Port $PORT is free"

echo -e "\n=== Step 2: Process existence ==="
ps aux | grep -E "vite.*dev|vue-cli-service" | grep -v grep || echo "❌ No active dev server process"

echo -e "\n=== Step 3: Env & config audit ==="
grep -n "VITE_PORT\|port.*$PORT" .env vite.config.* 2>/dev/null || echo "ℹ️  No explicit port override found"

echo -e "\n=== Step 4: Network binding check ==="
if command -v ss >/dev/null; then
  ss -tln | grep ":$PORT" || echo "❌ Not listening on any interface"
fi

六、架构视角：现代前端开发服务器的生命周期模型

graph TD
  A[执行 npm run dev] --> B{解析 package.json scripts}
  B --> C[加载 vite/bin/vite.js]
  C --> D[读取 vite.config.* 和 .env]
  D --> E[初始化 server 配置]
  E --> F[调用 createServer 创建 HTTP Server]
  F --> G[绑定到 server.host:server.port]
  G --> H{绑定成功？}
  H -->|Yes| I[打印 Local: http://localhost:5173/]
  H -->|No| J[抛出 ERROR: Port is already in use]
  J --> K[进程退出，返回 code 1]

该流程图揭示了为何“控制台看到启动命令但无日志输出”即代表卡在步骤 G —— 常见于 Docker 容器未映射端口、WSL2 网络未启用、或 systemd 用户服务未设置 LimitNOFILE 导致 bind 失败。

```