深入剖析 ECONNREFUSED 错误

在 TCP 连接 尝试 过程中，如果 目标 主机 对 连接 请求 主动 拒绝，就 会 抛出 ECONNREFUSED 错误，这一 情况 在 Linux 系统、Node.js 应用、Postman 调试 以及 各类 网络 客户端 中 都 时有 发生。错误 码 本身 反映 出 连接 建立 阶段 的 拒绝，常见 原因 包括 服务 未 启动、端口 与 地址 配置 不符、防火墙 或 安全 软件 拦截 以及 DNS 或 本地 hosts 配置 问题。针对 这一 错误，排查 思路 通常 包括 检查 目标 服务 状态、验证 主机 与 端口、排除 防火墙 干扰、测试 网络 连通 以及 分析 应用 日志 等 多 种 方法，借此 可 准确 定位 问题 并 实现 快速 修复。

ECONNREFUSED 错误 概述

定义 与 背景

ECONNREFUSED 是 一种 标准 网络 错误 码，标识 目标 主机 主动 拒绝 TCP 连接 尝试 (Errors | Node.js v23.11.0 Documentation)。该 错误 常见 于 客户端 调用 connect() 系统 调用 或 net.connect() 等 高层 API 时，操作 系统 或 底层 网络 堆栈 检测 到 目标 地址 或 端口 上 无 服务 进程 在 监听，就 会 返回 拒绝 信号 给 应用 (ECONNREFUSED when using connect() - LinuxQuestions.org)。

在 Node.js 环境 中，ECONNREFUSED 也 经常 出现在 使用 HTTP、TCP 套接字 或 各种 第三方 库（如 node-fetch、axios） 发起 请求 时，如果 指定 主机:端口 上 并 无 对应 服务，就 会 抛出 此 错误，并 在 错误 对象 中 包含 errno: -61 （或 类似 系统 返回 码）及 code: 'ECONNREFUSED' 信息 ('ECONNREFUSED' when trying to using socket to connect to remote ...)。

出现 场景

• 在 本地 开发 时，尝试 连接 MongoDB、MySQL、Redis 等 数据库 服务，却 未 启动 相应 服务，就 会 遇到 ECONNREFUSED (Node.js Error: connect ECONNREFUSED - Stack Overflow)。
• 在 前后端 分离 项目 中，前端 Debug 或 Postman 调试 请求 时，如果 后端 服务 未 正确 启动 或 CORS 配置 错误，同样 会 出现 该 错误 (Error: connect ECONNREFUSED 127.0.0.1:8080 - Ask the Experts ...)。
• 当 客户端 代码 部署 在 不同 网络 环境（如 容器、云 服务器）中，如果 防火墙 或 安全 组 阻止 特定 端口，连接 请求 也 会 被 拒绝 (How to Fix ECONNREFUSED - connection refused by server Error)。

ECONNREFUSED 发生 的 常见 原因

目标 服务 未 启动

如果 代码 中 有 数据库 连接、微服务 调用 等 逻辑，却 忘记 在 本地 或 服务器 上 启动 对应 服务，就 会 收到 主机 拒绝 连接 的 响应。以 Mongoose 连接 MongoDB 为例，执行：

mongoose.connect(`mongodb://localhost:27017/demoDb`);

若 未 执行 mongod 启动 命令，则 会 抛出 ECONNREFUSED (Node.js Error: connect ECONNREFUSED - Stack Overflow)。

地址 或 端口 配置 错误

使用 net.connect() 或 http.request() 调用 TCP 服务 时，如果 主机 名称 拼写 错误，或 指定 端口 与 服务 实际 监听 端口 不一致，也 会 导致 ECONNREFUSED。以 Node.js net API 为例，将 HOST 设置 为 错误 的 地址，就 会 立即 被 系统 拒绝：

const net = require(`net`);
net.connect({ host: `127.0.0.1`, port: 18000 });

若 端口 18000 上 无 服务 监听，就 会 抛出 错误 ('ECONNREFUSED' when trying to using socket to connect to remote ...)。

防火墙 或 安全 组 阻止

在 企业 或 云 平台 部署 场景 中，常见 操作 系统 自带 防火墙 或 云 服务 安全 组 的 端口 过滤 机制。如果 未 开放 相应 端口，任何 来自 外部 的 TCP 连接 都 会 被 丢弃 或 主动 拒绝，从 客户端 看 来 即 为 ECONNREFUSED (How to Fix ECONNREFUSED - connection refused by server Error)。

DNS 解析 或 本地 hosts 配置 问题

当 使用 域名（如 api.example.com）而 非 IP 时，若 DNS 解析 结果 不 正确，或 本地 hosts 文件 强制 指向 错误 地址，也 会 导致 客户端 发往 本应 有 服务 的 主机 却 被 系统 拒绝。更新 DNS 或 清理 hosts 可 是 解决 途径 (Error ECONNREFUSED every time I try to hit an API endpoint)。

库 内 部 Bug 或 平台 差异

某些 第三方 库（如 node-fetch）在 不同 Node.js 版本 中 对 localhost 和 127.0.0.1 的 处理 存在 差异，可能 会 无法 正确 建立 连接，从 而 抛出 ECONNREFUSED。对比 调整 为 IP 地址，或 降级/升级 Node.js 版本，往往 能 解决 问题 (ECONNREFUSED on NodeJS 18 · Issue #1624 - GitHub)。

排查 与 解决 ECONNREFUSED

核实 目标 服务 状态

应 当 在 服务器 或 本地 机器 上，运行 ps、netstat -tlnp、ss -tlnp 等 命令，确认 目标 端口 是否 真正 有 进程 在 监听。例如：

ss -tlnp | grep 27017

若 未 找到 对应 服务，请 启动 或 重启 (ECONNREFUSED when using connect() - LinuxQuestions.org)。

验证 主机 与 端口

务必 确认 客户端 配置 与 服务 实际 监听 的 主机、端口 完全 匹配，并 考虑 IPv4/IPv6 间 的 差异。遇 到 不 确定 时，可 在 本地 使用 telnet 或 nc 工具 进行 端口 连接 测试：

telnet localhost 8080

若 出现 Connection refused，就 意味 着 服务 并 未 在 该 端口 监听 (Error: connect ECONNREFUSED 127.0.0.1:8080 - Ask the Experts ...)。

排除 防火墙 干扰

对于 Linux 系统，可 临时 关闭 ufw 或 firewalld 进行 验证；在 云 平台 上，则 应 检查 安全 组 或 网络 ACL 规则。确认 端口 已 放行 才能 排除 防火墙 因素 (How to Fix ECONNREFUSED - connection refused by server Error)。

测试 网络 连通

在 分布式 环境 中，客户端 与 服务器 可能 位于 不同 子网。使用 ping、mtr 等 工具 测试 网络 延迟 与 丢包，并 确保 中间 负载 均衡、代理 或 NAT 设备 未 干预 TCP 握手 (Step-by-Step Fix "ECONNREFUSED - Connection refused by server ...)。

分析 应用 日志

将 客户端 与 服务端 日志 都 置于 DEBUG 级别，关注 连接 建立、TLS 握手（如 HTTPS）及 身份 验证 等 过程，往往 能 发现 除 端口 无 服务 外 的 其他 错误 根源 (Node.js Connection Refused - Auth0 Community)。

真实 案例 研究

案例 一：本地 MongoDB 连接 未 启动

在 一 项 Node.js 项目 中，开发 者 使用 Mongoose 连接 mongodb://localhost:27017/appDb，却 遇到 ECONNREFUSED，经 排查 后 发现 本地 并 未 执行 mongod 命令 来 启动 数据库 服务，补 启 动 后 问题 即 可 解决 (Node.js Error: connect ECONNREFUSED - Stack Overflow)。

案例 二：Docker 容器 内 部 服务 不 可 达

某 团队 在 Docker Compose 环境 中，尝试 从 一个 容器 A 访问 B 容器 上 的 HTTP 服务，却 收到 ECONNREFUSED，检查 后 发现 应 用 指向 localhost，实际上 应 指向 service-b:3000，调整 hosts 或 Compose 网络 后，连接 恢复 正常 (Step-by-Step Fix "ECONNREFUSED - Connection refused by server ...)。

小结

通过 对 ECONNREFUSED 错误 的 起因、排查 与 修复 手段 的 系统 分析，可 见 这一 常见 网络 错误 并 非 难 题。关键 在于 确保 目标 服务 正常 启动 并 在 正确 主机/端口 上 监听，同时 排除 防火墙、DNS 解析 及 配置 差异 等 多 种 影响 因素。借助 系统 工具、网络 调试 和 日志 分析，能够 快速 定位 根本 原因，使 应用 连接 保持 稳定。