db.auth() 返回 0 表示认证失败，即凭据校验不通过，常见原因包括密码含未编码特殊字符、authSource库名不匹配、用户不存在或密码为空、认证机制不兼容（如SCRAM-SHA-1与SHA-256混用）、角色权限不足等。
db.auth() 返回 0 是什么含义
db.auth() 返回 0 表示认证失败，不是“连接失败”或“网络超时”，而是明确的凭据校验不通过。MongoDB 不会告诉你具体哪部分错了（比如是密码错、库名错还是机制不匹配），只给一个布尔式反馈。这个返回值本身不带错误堆栈，容易让人误以为是服务端问题，其实绝大多数情况都出在客户端配置或账号状态上。
用户名密码错误的典型表现和验证方式
最常见原因就是明文密码里含特殊字符（如 @、/、:、%）但没做 URI 编码，或者复制粘贴时多空格、全角字符混入。直接在 mongosh 里用 db.auth("user", "pass") 测试时也一样会失败。
- 用
passwordPrompt()替代明文传参，避免终端历史泄露和编码干扰：db.auth("root", passwordPrompt()) - 若仍返回
0，立刻切到admin库执行db.getUsers({filter: {user: "root"}})，确认该用户是否存在、pwd字段是否为空（说明创建时未设密） - 注意：MongoDB 6.0+ 默认禁用
SCRAM-SHA-1，如果旧账号是用它创建的，而服务端已强制SCRAM-SHA-256，db.auth()也会静默返回0
authSource 数据库名不匹配的排查要点
很多人以为“账号是 admin 库建的，连任何库都要加 ?authSource=admin”，其实不对——db.auth() 本身不读连接串参数，它只在当前 use 的库上下文中执行认证。也就是说，如果你 use test 后调 db.auth("u", "p")，MongoDB 就默认去 test 库查用户凭证，哪怕你账号其实在 admin 里。
- 执行
db.auth()前，必须先use到账号所在的认证数据库（通常是admin） - 用
db.runCommand({connectionStatus: 1})查看当前连接的authInfo.db字段，它显示的是实际生效的认证库名 - 如果应用连接字符串写了
?authSource=otherdb，但你手动进 shell 后没use otherdb就调db.auth()，照样返回0
容易被忽略的权限与机制兼容性问题
返回 0 还可能因为账号有“名”无“权”：比如用户文档里 roles 是空数组，或只给了 read 却试图在 admin 库执行 db.auth()（需要 root 或 __system 角色）。
- 检查用户角色是否包含
clusterAdmin或userAdminAnyDatabase等跨库权限（仅当需在非认证库操作时才关键） - 运行
db.runCommand({saslSupportedMechs: "admin.$external"})确认服务端支持的认证机制，再比对db.auth({mechanism: "SCRAM-SHA-256", ...})是否显式匹配 - 在容器或云服务（如阿里云 MongoDB 版）中，
db.auth()可能被代理层拦截或降级，此时应优先用平台提供的连接测试工具而非本地 shell
真正卡住人的往往不是“不知道怎么试”，而是试的时候没锁定上下文：当前库、当前连接参数、当前服务端启用的机制，三者缺一不可。随便换一个，db.auth() 就只给你一个冷冰冰的 0。
