Node.js 20.3.1连接MongoDB Atlas触发DEP0170警告的解决方法

问题背景 #

升级Node.js至20.3.1版本后，连接MongoDB Atlas时终端弹出[DEP0170]弃用警告，提示当前使用的URL无效，未来Node.js版本会直接抛出错误。此前使用Node.js 19.X版本时连接完全正常，目前数据库仍可正常连接，但未找到该警告的解决办法。

原连接配置 #

MONGODB_URI=mongodb+srv://<USERNAME>:<PASSWORD>@<USERNAME>.nqjamzn.mongodb.net/<DATABASE>?retryWrites=true&w=majority

警告内容 #

[DEP0170] DeprecationWarning: The URL mongodb://:@ac-4hlp44x-shard-00-01.nqjamzn.mongodb.net:27017,ac-4hlp44x-shard-00-02.nqjamzn.mongodb.net:27017,ac-4hlp44x-shard-00-00.nqjamzn.mongodb.net:27017/?authSource=admin&replicaSet=atlas-g8a2vr-shard-0&retryWrites=true&w=majority&ssl=true is invalid. Future versions of Node.js will throw an error.

解决步骤 #

从警告里的解析后URL能看到，用户名和密码字段是空的（mongodb://:@...），这是Node.js 20对URL解析规则收紧导致的，按以下步骤排查修复：

• 转义账号中的特殊字符：如果你的MongoDB用户名或密码包含@、:、/、%这类特殊字符，必须将其转换为URL编码格式。比如@替换为%40，:替换为%3A，/替换为%2F。
• 确认环境变量替换生效：检查<USERNAME>和<PASSWORD>是否已经被正确替换为实际的账号信息，没有留空或替换失败的情况。
• 升级MongoDB驱动版本：Node.js 20的URL解析逻辑更严格，旧版本驱动可能未适配该变化。将mongodb包升级到最新稳定版（推荐5.x及以上），新版驱动会自动处理URL的正确解析与转义。
• 显式指定认证源：在连接URL末尾追加&authSource=admin，明确指定认证源，避免解析时出现异常。

修改后重新测试连接，确认警告消失且数据库连接正常。

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