ETIMEDOUT 表示 TCP 连接超时，非 ICMP 层问题；需依次排查 DNS 解析、目标端口可达性、TLS 握手、客户端代理/连接池及 IPv6 回退失败等五类原因。
如果您尝试调用某个API接口，日志显示 ETIMEDOUT 错误，但执行 ping 命令却能正常通达目标主机，则说明 ICMP 层可达，而 TCP 连接层失败。以下是解决此问题的步骤：
一、DNS解析未完成或异常
DNS 解析失败或延迟会导致连接请求卡在域名解析阶段，此时 ping 可能使用缓存 IP 或系统 hosts 映射绕过 DNS，造成“能 ping 通但连接超时”的假象。需验证实际解析结果是否与服务监听地址一致。
1、执行 dig +short api.example.com A 查询权威 A 记录，确认返回的 IP 地址是否为目标服务真实监听地址。
2、运行 nslookup api.example.com，检查是否返回 IPv6 地址且本地网络不支持 IPv6，导致连接回退失败。
3、对比 node -e "require('dns').lookup('api.example.com', (err, addr) => console.log(addr))" 输出，确认 Node.js 运行时解析结果是否与系统命令一致。
二、目标端口未开放或被拦截
TCP 连接需完成三次握手，ping 仅验证 ICMP 可达性，无法反映特定端口的服务状态。ETIMEDOUT 往往发生在 connect() 系统调用阶段，表明 SYN 包发出后未收到 SYN-ACK 响应，常见于防火墙丢包、端口未监听或中间设备策略拦截。
1、使用 telnet api.example.com 443（替换为实际端口）测试端口连通性，若提示 Connection refused 则端口有响应；若长时间无响应或报 Connection timed out，则端口被静默丢弃。
2、执行 nc -zv api.example.com 443，观察输出是否显示 succeeded 或 failed，该命令更贴近应用层 TCP 行为。
3、在客户端机器上运行 sudo tcpdump -i any host api.example.com and port 443，抓包确认是否有 SYN 发出及是否收到 SYN-ACK。
三、服务端 TLS 握手阻塞
当接口使用 HTTPS 协议时，ETIMEDOUT 可能发生在 TLS 握手阶段而非 TCP 连接建立阶段。此时 TCP 连接已建立，但服务器在证书交换、密钥协商等环节无响应，客户端因等待超时而中断。
1、使用 openssl s_client -connect api.example.com:443 -servername api.example.com 测试 TLS 握手流程，观察是否卡在 CONNECTED(00000000) 后无进一步输出。
2、添加 -debug 参数重放握手过程，确认是否在 Certificate、ServerKeyExchange 或 ChangeCipherSpec 阶段停滞。
3、检查服务端是否启用 SNI 扩展且配置了正确的 servername，客户端未传 SNI 可能导致服务端无响应。
四、客户端连接池或代理干扰
Node.js 等运行时默认启用 HTTP Agent 连接池，并内置 DNS 缓存、ALPN 协商、SNI 扩展等机制，其行为与 ping/telnet 等基础工具存在本质差异。代理配置错误或连接复用异常也会引发静默超时。
1、临时禁用代理：设置环境变量 NODE_OPTIONS="--no-proxy" 或在代码中显式配置 agent: false。
2、复现底层请求逻辑：运行 node -e "require('https').get('https://api.example.com/', r => console.log(r.statusCode)).on('error', e => console.error(e.code, e.syscall, e.address))"，捕获真实错误源头及解析出的 IP 地址。
3、清除 Node.js 内置 DNS 缓存：调用 require('dns').setServers(['8.8.8.8']) 强制使用公共 DNS，并重启进程。
五、IPv6 回退失败或双栈冲突
现代操作系统默认启用 IPv6，当 DNS 返回 AAAA 记录但网络不支持 IPv6 时，客户端可能先尝试 IPv6 连接并超时，再回退至 IPv4。若回退机制异常或超时阈值过短，将导致整体连接失败，而 ping 可能仅走 IPv4 路径。
1、执行 ip -6 route show 检查本地 IPv6 路由是否存在有效网关，若无则强制禁用 IPv6 尝试。
2、在 Node.js 中设置环境变量 NODE_OPTIONS="--ipv4" 强制使用 IPv4 协议栈。
3、使用 curl -4 https://api.example.com 测试 IPv4 专用连接，对比 -6 参数下的行为差异。
