必须对用户名、密码、数据库名中的@、/、:、+等特殊字符用encodeURIComponent编码，其他部分（主机、端口、查询参数）保持原样；错误做法是全量编码或遗漏 dbname。
MongoDB连接字符串里有@、/、:、+这些字符会直接报错
Node.js 的 mongodb:// 连接字符串对用户名、密码、数据库名里的特殊字符非常敏感。比如密码是 pa@ss/w0rd+123，不处理就直接拼进 URL，mongo 驱动会把 @ 当作用户名与主机分隔符，把 / 当作路径起始，结果连不上，报错类似：MongoParseError: Invalid connection string 或 Authentication failed。
根本原因不是驱动 bug，而是 URL 规范要求这些字符必须编码。不能靠“换密码”回避——生产环境密码策略往往强制含特殊字符。
只对用户名、密码、数据库名用 encodeURIComponent，其他部分不动
encodeURIComponent 是正确解法，但容易误用：有人把整个连接字符串都 encode，导致 mongodb:// 被转成 mongodb%3A%2F%2F，驱动完全无法识别；也有人漏掉数据库名（尤其是带 - 或 . 的），其实 . 在数据库名里虽合法，但出现在 URL 路径中会被误解析。
- 需要编码的只有三处：
username、password、dbname - 主机地址（如
cluster0.xyx.mongodb.net）、端口、查询参数（如?retryWrites=true）一律不编码 - 如果用户名或密码为空，不要传空字符串，应省略对应字段（即不写
:@）
示例：
const username = encodeURIComponent('dev@team');
const password = encodeURIComponent('p@ss/w0rd+123');
const dbname = encodeURIComponent('my-app.db');
const uri = `mongodb+srv://${username}:${password}@cluster0.xyx.mongodb.net/${dbname}?retryWrites=true&w=majority`;
使用 URL 构造函数动态拼接更安全
手拼字符串易出错，尤其当用户名/密码含 %（比如原密码就是 URL 编码过的）。用 URL 构造函数可自动处理编码边界：
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
const url = new URL('mongodb+srv://host/dbname?retryWrites=true');
url.username = encodeURIComponent('u@ser');
url.password = encodeURIComponent('p@ss/w0rd');
url.pathname = '/' + encodeURIComponent('my.db');
const uri = url.toString();
注意：URL 构造函数对 mongodb+srv:// 协议支持良好，但旧版 Node.js（+srv，此时降级用 mongodb:// 即可，逻辑不变。
如果项目已用 dotenv 读取凭据，别在 .env 文件里提前 encode——让代码在运行时做，否则不同环境（如本地 vs Docker）可能因 shell 解析差异导致双重编码。
连接失败时优先检查编码后的字符串是否被二次 decode
常见陷阱：后端把已 encode 的密码再过一遍 decodeURIComponent，或者日志打印时自动还原，导致你看到的“原始密码”其实是解码后的，误以为没生效。验证方法很简单：
- 打印最终拼出的
uri字符串（不是原始变量），确认@变成了%40、/变成了%2F - 用
new URL(uri)解析它，看.username和.password属性是否还原为你期望的明文（这是正常行为） - 如果驱动报
Authentication failed但编码无误，大概率是账号没权限或 IP 白名单没开，和编码无关
真正难调试的是嵌套场景：比如密码从 KMS 拉取后带换行符，encodeURIComponent 不处理换行，但 MongoDB 会静默截断——这种得在 encode 前先 .trim()。
