Node.js 网络问题：端口占用与网络超时

Error: listen EADDRINUSE: address already in use :::3000 与 Error: connect ETIMEDOUT 是 Node.js 服务运行阶段最高频的网络拦截异常。端口占用直接阻断服务启动，网络超时则引发请求堆积与内存泄漏。以下指南按排查优先级提供可执行的修复路径。

阶段一：定位与解除端口占用

端口被占用通常由进程未正常退出、重复启动脚本或第三方软件冲突引起。按顺序执行以下命令即可精准回收端口。

1. 读取终端报错堆栈，提取提示文本末尾的端口数值（如 3000、8080、4000）。
2. 查询系统级端口占用明细。macOS 与 Linux 终端执行 sudo lsof -i :<端口号> -sTCP:LISTEN；Windows 终端执行 netstat -ano | findstr :<端口号>。将 <端口号> 替换为实际数值，忽略输出中 TIME_WAIT 状态的记录。
3. 提取占用进程的标识符（PID）。系统返回结果的最后一列即为 PID 值，Windows 环境可能需横向滚动终端查看最右侧数字列。
4. 强制终止冲突进程。macOS 与 Linux 执行 sudo kill -9 <PID>；Windows 执行 taskkill /PID <PID> /F。
5. 校验端口释放状态。重新执行阶段二的查询命令，确认终端无返回内容即代表端口已处于空闲状态。
6. 限制服务监听网卡范围避免隐式冲突。将代码中的 app.listen(<端口号>) 修改为 app.listen(<端口号>, '127.0.0.1')，强制 Node.js 仅绑定本地 IPv4 回环地址，避开 Docker 容器或虚拟机网桥引发的 IPv6 地址抢占。
7. 注册进程优雅退出信号监听。在入口文件顶层添加 process.on('SIGTERM', () => { server.close(() => process.exit(0)); }) 与 process.on('SIGINT', () => { server.close(() => process.exit(0)); })，确保系统发送关闭信号时主动释放底层 Socket 句柄。

阶段二：分级排查网络超时

网络超时并非单一故障，需隔离 DNS 解析延迟、TCP 握手失败、SSL 协商卡顿与数据传输中断四个维度。

1. 验证域名解析链路。终端执行 nslookup 目标域名 8.8.8.8 与 ping 目标域名，对比公共 DNS 与本地运营商 DNS 的响应耗时。若本地解析耗时超过五百毫秒，配置 /etc/resolv.conf（Linux）或 scutil --dns（macOS）优先使用 114.114.114.114 或 8.8.8.8。
2. 探测 TCP 连通性阈值。执行 telnet 目标域名 <目标端口> 或 curl -o /dev/null -s -w "%{time_connect} %{time_starttransfer} %{time_total}\n" https://目标域名，对比三段时间指标。若 time_connect 极长，检查本地防火墙出站规则或中间网络设备拦截策略。
3. 开启 Node.js 底层网络模块调试日志。在终端添加环境变量 NODE_DEBUG=net,http,http2,stream 后启动服务，过滤控制台输出的 socket timeout 与 agent keep-alive 关键词，定位具体阻塞的请求实例。
4. 覆盖 HTTP 代理连接池默认上限。Node.js 默认对同一目标主机的最大并发连接数限制为五，高并发场景易引发请求排队。在发起请求的配置对象中注入自定义 Agent：

   
   import http from 'node:http';
   import https from 'node:https';

const agent = new https.Agent({
keepAlive: true,
maxSockets: 100,
maxFreeSockets: 10,
timeout: 30000,
freeSocketTimeout: 15000
});

5. **核对**请求库超时参数映射关系。不同网络库对超时阶段的定义与单位存在差异，需按实际引入的模块精准赋值，避免参数传递失效。

| 请求库 | 连接建立阶段配置项 | 响应接收阶段配置项 | 计量单位 | 默认行为差异 |
| :--- | :--- | :--- | :--- | :--- |
| `axios` | `timeout` | `timeout` | 毫秒 `ms` | 统一控制总耗时 |
| `undici` | `connect` | `bodyTimeout` | 毫秒 `ms` | 独立阶段隔离 |
| `node-fetch` v3 | 依赖 AbortController | 依赖 AbortController | 毫秒 `ms` | 需外部定时器中断 |
| `got` | `timeout.connect` | `timeout.response` | 毫秒 `ms` | 自动拆分网络阶段 |
| 原生 `http.request` | `options.timeout` | `socket.setTimeout()` | 毫秒 `ms` | 底层流式控制 |

6. **注入**独立连接保活探测。针对长连接业务，在创建 Agent 时**启用** `keepAlive: true` 并**设置** `keepAliveMsec` 为三万毫秒，**强制** Node.js 定期发送空数据包维持链路活跃，防止防火墙或负载均衡器切断闲置连接。

---

## 阶段三：植入代码级容错策略
依赖外部网络的服务必须具备自动恢复能力，通过重试退避、快速失败与降级熔断阻断级联故障。

1. **计算**指数退避重试间隔。避免固定频率重试导致目标服务器雪崩，**应用** `delay = Math.min(1000 * Math.pow(2, attempt), 15000)` 公式，确保首次重试等待一秒，后续间隔翻倍且硬顶限制在十五秒内。
2. **编写**带重试拦截的客户端封装。使用 `axios` 拦截器捕获 `ECONNABORTED` 与 `ETIMEDOUT` 错误码，参考以下实现结构：
```javascript
import axios from 'axios';

const resilientClient = axios.create({
  baseURL: 'https://api.third-party.com',
  timeout: 6000,
  headers: { 'Accept': 'application/json' }
});

resilientClient.interceptors.response.use(
  (res) => res,
  async (error) => {
    const config = error.config;
    if (!config || config._retryLimit !== undefined) {
      return Promise.reject(error);
    }

    const maxAttempts = 3;
    const currentAttempt = config._attempt || 0;
    config._attempt = currentAttempt + 1;

    if (currentAttempt < maxAttempts) {
      const backoffDelay = Math.min(1000 * Math.pow(2, currentAttempt), 15000);
      await new Promise(resolve => setTimeout(resolve, backoffDelay));
      return resilientClient(config);
    }

    return Promise.reject(new Error(`Max retry attempts reached: ${currentAttempt}`));
  }
);

export default resilientClient;

3. 全局替换分散的请求调用点。遍历业务目录搜索 axios.get、fetch 或 request 关键字，替换为导入 resilientClient 的标准化调用，清理冗余的本地 try-catch 与手动重试逻辑。
4. 挂载未捕获网络异常监控器。在主进程文件头部注册 process.on('unhandledRejection', (reason) => { ... }) 回调，解析错误堆栈中的 syscall 与 address 字段，当匹配到 getaddrinfo ENOTFOUND 时记录域名拼写错误或 DNS 污染状态，触发运维告警后按业务等级决定是否降级。
5. 实施本地缓存降级策略。定义环境变量 ENABLE_NETWORK_FALLBACK=true，在拦截器中拦截连续失败请求，查询本地 Redis 或文件系统缓存，若命中历史有效数据则直接返回缓存载荷并附加 X-Cache-Fallback: true 响应头，保障核心链路可用性。