本指南详细解析 MongoServerSelectionError: connect ECONNREFUSED ::1:27017 错误的根本原因——通常由本地 MongoDB 服务未运行或地址解析异常引起，并提供即时可用的修复方法、健壮的连接代码以及关键注意事项。
开发中遇到 MongoDB 连接失败，报错信息为 `MongoServerSelectionError: connect ECONNREFUSED ::1:27017`？不必慌张。这是 Node.js 连接 MongoDB 时极为常见的网络层错误，表示客户端尝试通过 IPv6 地址 ::1（即 localhost 的 IPv6 表示）连接 27017 端口被拒绝。根本原因通常不是代码问题，而是 MongoDB 服务未启动，或监听配置与连接地址不一致。
理解这一根本原因后，解决问题就有了明确的方向。
诊断与修复方案：从确认服务状态入手
确认 MongoDB 服务运行状态
这是排查的第一步，也最容易被忽略。打开终端运行以下命令：# Windows（命令提示符或 PowerShell）mongod --version# 然后检查服务状态（若以服务方式安装）：sc query MongoDB
# macOS/Linuxbrew services list | grep mongodb # Homebrew 安装sudo systemctl status mongod # systemd 管理
如果服务未运行，启动它：
# macOS（Homebrew）brew services start mongodb-community# Linux（systemd）sudo systemctl start mongod# Windows（管理员权限运行）net start MongoDB
验证 MongoDB 监听情况
仅启动服务还不够，需要确认它确实在监听 27017 端口。运行：telnet localhost 27017# 或使用 curl（需安装 mongo-tools）mongosh --eval "db.runCommand({ping:1})"如果连接超时或直接拒绝，表明服务未监听该端口。
调整连接URL（必要时）
`mongodb://localhost:27017/` 写法看似正确，但存在一个隐藏问题：某些系统会优先将 localhost 解析为 IPv6 地址 ::1，而 MongoDB 可能仅绑定 IPv4，导致连接失败。最直接的解决方案是显式指定 IPv4 地址：const url = "mongodb://127.0.0.1:27017/"; // ✅ 推荐：强制 IPv4// 或（不推荐用于生产）// const url = "mongodb://0.0.0.0:27017/";
⚠️ 注意：0.0.0.0 表示监听所有 IPv4 接口，仅限开发环境使用，生产环境严禁使用（存在严重安全风险）；127.0.0.1 是更安全、明确的本地回环地址。
健壮且现代化的连接代码（适配 MongoDB Driver v6+）
早期的代码使用 `MongoClient.connect()` 回调方式，在新的驱动版本中已被弃用，且缺少完善的错误处理与资源释放机制。以下是推荐的 Promise + try/catch 写法，兼容 v4.12+ 和 v6.x：
const { MongoClient } = require("mongodb");async function run() { const client = new MongoClient("mongodb://127.0.0.1:27017/", { serverSelectionTimeoutMS: 5000, // 缩短超时便于调试 connectTimeoutMS: 3000, }); try { await client.connect(); // 显式等待连接建立 console.log("✅ Successfully connected to MongoDB"); const db = client.db("school"); const collection = db.collection("students"); // 创建集合（可选，insertMany 会自动创建） await collection.createIndex({}); // 确保集合存在 console.log("? Collection 'students' is ready"); // 插入数据 const myObjList = [ { name: "rohit", age: 15, gpa: 4.9 }, { name: "rahul", age: 17, gpa: 4.7 }, ]; const result = await collection.insertMany(myObjList); console.log(`✅ Inserted ${result.insertedCount} documents`); } catch (error) { console.error("❌ Connection or operation failed:", error.message); // 输出具体错误类型便于定位 if (error.name === "MongoServerSelectionError") { console.error("? Hint: Is MongoDB service running and bound to 127.0.0.1:27017?"); } } finally { await client.close(); // 确保连接关闭 console.log("? Connection closed"); }}run();关键注意事项与最佳实践
- 服务验证绝不可跳过：约 90% 的 ECONNREFUSED 错误源于 MongoDB 服务未启动，与代码逻辑无关。
- 警惕 localhost 的 IPv6 陷阱：请检查 `/etc/hosts`（macOS/Linux）或 `C:WindowsSystem32driversetchosts`（Windows）文件，确认 localhost 是否被错误映射为 ::1。临时改用 127.0.0.1 是最快捷的验证方法。
- 驱动版本兼容性：Node.js MongoDB Driver v6+ 已移除回调接口，必须使用 async/await 或 .then() 进行异步操作。旧版 `MongoClient.connect(url, callback)` 在新版本中会直接报错。
- 连接池与生命周期管理：`MongoClient` 实例应全局复用，避免每次操作都新建客户端；`client.close()` 仅在应用退出前调用一次，而不是每次数据库操作后都执行。
按照以上步骤逐一排查，连接拒绝问题基本可解决，并能够构建一套稳定且易于维护的 MongoDB 数据接入层。
