部署时出现MongoDB认证错误，本地运行正常求助

先贴出你遇到的错误：

5:30:38 PM: [nodemon] starting `node server.js`
5:30:39 PM: Server listening on http://localhost:3000
5:30:39 PM: /opt/build/repo/node_modules/mongodb/lib/cmap/connection.js:202
5:30:39 PM:                 callback(new error_1.MongoServerError(document));
5:30:39 PM:                          ^
5:30:39 PM: MongoServerError: bad auth : authentication failed
5:30:39 PM:     at Connection.onMessage (/opt/build/repo/node_modules/mongodb/lib/cmap/connection.js:202:26)
5:30:39 PM:     at MessageStream.<anonymous> (/opt/build/repo/node_modules/mongodb/lib/cmap/connection.js:61:60)
5:30:39 PM:     at MessageStream.emit (node:events:517:28)
5:30:39 PM:     at processIncomingData (/opt/build/repo/node_modules/mongodb/lib/cmap/message_stream.js:124:16)
5:30:39 PM:     at MessageStream._write (/opt/build/repo/node_modules/mongodb/lib/cmap/message_stream.js:33:9)
5:30:39 PM:     at writeOrBuffer (node:internal/streams/writable:392:12)
5:30:39 PM:     at _write (node:internal/streams/writable:333:10)
5:30:39 PM:     at Writable.write (node:internal/streams/writable:337:10)
5:30:39 PM:     at TLSSocket.ondata (node:internal/streams/readable:809:22)
5:30:39 PM:     at TLSSocket.emit (node:events:517:28) {
5:30:39 PM:   ok: 0,
5:30:39 PM:   code: 8000,
5:30:39 PM:   codeName: "AtlasError",
5:30:39 PM:   connectionGeneration: 0,
5:30:39 PM:   [Symbol(errorLabels)]: Set(2) { "HandshakeError", "ResetPool" }
5:30:39 PM: }

以下是针对本地正常、部署报错的排查方向：

• 核实部署环境的环境变量
  别只看变量名对不对，直接在部署日志里打印出实际读取的连接字符串（比如加console.log('Mongo URI:', process.env.MONGO_URI)），检查：

  • 用户名/密码有没有写错，尤其是复制粘贴时带了隐形空格、换行符；
  • 密码里的特殊字符（@、$、!等）有没有做URL编码，比如abc@123要转成abc%40123，本地可能自动处理，但部署环境不一定。

• 检查MongoDB Atlas的IP白名单
  本地能连是因为你的本地IP在白名单里，但部署服务器的IP大概率不在。去Atlas控制台的网络访问设置里，把部署平台的出站IP加进去，或者临时开放0.0.0.0/0测试（测试完记得改回指定IP，别留安全隐患）。

• 确认连接字符串格式
  检查URI是否完整，比如是不是mongodb+srv://<username>:<password>@cluster-name.mongodb.net/<db-name>?retryWrites=true&w=majority这种标准格式，有没有漏了集群地址、数据库名，或者参数写错。

• 对齐Node版本
  本地Node版本和部署环境的Node版本差异过大，可能导致Mongo驱动兼容性问题。去部署平台设置里把Node版本改成和本地一致的版本（比如用nvm ls看本地版本）。

• 重新生成用户凭证
  哪怕你确认密码没错，也去Atlas控制台删掉现有用户，重新创建一个新用户，复制新的密码到部署环境变量里，避免旧凭证的缓存或未知问题。

内容的提问来源于stack exchange，提问作者Karli Christensen