MongoDB连接失败主因是authSource与用户创建库不一致、驱动选项配置错误或用户权限不足；须确保连接串authSource匹配建户库、3.x驱动启用useNewUrlParser和useUnifiedTopology、用户具备目标库读写角色。
连接字符串里必须带用户名密码和认证数据库
不加 authSource 或写错认证库名，十有八九连不上，报错通常是 MongoServerError: Authentication failed。MongoDB 4.0+ 默认用 admin 库做认证，但如果你是用 db.createUser() 在某个业务库（比如 myapp）里建的用户，那 authSource 就得设成那个库名。
实操建议：
- 连接字符串格式：
mongodb://: @localhost:27017/ ?authSource= - 如果用户建在
admin，authSource=admin；建在myapp，就写authSource=myapp - 密码里含特殊字符（如
/、@、:）必须用encodeURIComponent()编码，否则解析会出错 - 别把密码硬编码进字符串——用环境变量读取，比如
mongodb://${process.env.DB_USER}:${encodeURIComponent(process.env.DB_PASS)}@...
用 MongoClient 连接时别漏掉 useNewUrlParser 和 useUnifiedTopology
这两个选项不是可选的“优化开关”，而是影响连接行为的关键开关。旧版驱动（3.x）默认关，不显式开启会导致解析失败、重连异常，甚至静默丢连接。
常见错误现象：连接没报错，但后续 collection.find() 一直 pending，或抛 ServerSelectionError。
实操建议：
- Node.js + MongoDB Driver 4.x+ 已废弃这两个选项，但如果你还在用 3.x（比如因 legacy 项目卡在 Node 12），必须设为
true - 正确写法：
const client = new MongoClient(uri, { useNewUrlParser: true, useUnifiedTopology: true }); - Driver 4.x+ 只需传
uri和必要选项（如maxPoolSize），其他自动处理
认证失败时先检查用户权限和角色，不是改代码
连不上，第一反应不该是调连接参数，而是确认 MongoDB 侧的用户有没有被正确定义和授权。很多问题其实跟 Node.js 无关。
使用场景：本地开发连自己搭的副本集，或上云后连 Atlas/阿里云 MongoDB。
实操建议：
- 登录 mongo shell，执行
use admin→db.getUser("myuser")，看返回里roles是否包含对目标库的操作权限（如{ role: "readWrite", db: "myapp" }） - Atlas 用户默认只对指定数据库有权限，不能靠
authSource=admin绕过；阿里云 MongoDB 控制台创建用户时，要手动勾选对应库的权限 - 副本集环境下，认证必须指向主节点，或者用完整种子列表（
host1:27017,host2:27017,host3:27017），单写一个从节点地址可能认证失败
环境变量里存凭证，但别让 .env 被 git 提交
本地用 dotenv 加载很方便，但一不小心就把密码提交到仓库，尤其团队协作时，这个坑踩过的人太多。
性能 / 兼容性影响：无直接性能影响，但泄露凭证会导致数据完全失控，比任何慢查询都致命。
实操建议：
- 确保
.gitignore包含.env，且已用git rm --cached .env清除历史记录 - 在代码里加基础校验：
if (!process.env.DB_USER || !process.env.DB_PASS) { throw new Error("Missing DB credentials in environment"); } - CI/CD 环境用平台原生密钥管理（如 GitHub Secrets、GitLab CI Variables），别往
.env里塞
MongoDB 认证连通性的关键不在 Node.js 代码多精巧，而在三处对齐：连接串里的 authSource 和实际建用户的库一致、驱动版本和选项匹配、用户角色真能操作目标集合。这三点任意一个偏移，都会卡在“连得上但查不了”这种最磨人的状态。
