forRootAsync 是唯一可靠选择，因它支持异步动态构造URI、自动编码密码、条件注入replicaSet/authSource等参数，避免硬编码导致的环境切换失败、认证错误或静默写入失败。
必须用 MongooseModule.forRootAsync，不能用 forRoot 硬编码 URI —— 否则环境切换会失败、密码特殊字符会解析错、认证参数会漏掉。
为什么 forRootAsync 是唯一可靠选择
硬编码 mongodb://... 在 forRoot 里，等于把开发库地址、密码、副本集参数全写死。一旦部署到生产环境，要么连不上，要么连错库，要么认证失败且错误不明显（尤其 authSource 缺失时，连接成功但写入静默失败）。
forRootAsync 提供了执行时机可控的异步配置入口，能自然接入 ConfigService、做 URL 编码、条件拼接参数。它不是“更高级的写法”，而是多环境落地的底线要求。
- 所有环境变量（
MONGODB_URI、NODE_ENV）必须由ConfigService统一读取，不能直接用process.env - 如果
MONGODB_URI未定义，forRootAsync会抛出明确错误，而forRoot可能静默降级为本地连接 - 支持在
useFactory中做运行时校验，比如检查 URI 是否含replicaSet（云环境必需）或是否漏authSource
如何安全构造带认证的 MongoDB URI
密码含 @、/、: 时，字符串拼接一定会崩。例如 user:pa@ss/w0rd@host/db 会被解析成用户名 user、密码 pa、主机 ss/w0rd@host —— 显然错得离谱。
Comprehensive Three.js 3D graphics reference
下载
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
正确做法只有一条：**不要手动拼接 URI，改用 useFactory + encodeURIComponent 分别编码用户和密码**：
MongooseModule.forRootAsync({
useFactory: async (configService: ConfigService) => {
const username = encodeURIComponent(configService.get('MONGODB_USER'));
const password = encodeURIComponent(configService.get('MONGODB_PASSWORD'));
const host = configService.get('MONGODB_HOST');
const port = configService.get('MONGODB_PORT');
const dbName = configService.get('MONGODB_DB_NAME');
const authSource = configService.get('MONGODB_AUTH_SOURCE') || 'admin';
const replicaSet = configService.get('MONGODB_REPLICA_SET');
let uri = `mongodb://${username}:${password}@${host}:${port}/${dbName}?authSource=${authSource}`;
if (replicaSet) {
uri += `&replicaSet=${replicaSet}`;
}
return {
uri,
useNewUrlParser: true,
useUnifiedTopology: true,
connectTimeoutMS: 10000,
socketTimeoutMS: 30000,
};
},
inject: [ConfigService],
});
-
useNewUrlParser和useUnifiedTopology必须显式设为true，即使 Mongoose ≥6.x 默认启用，Nest 封装层仍依赖此声明 - 云服务（如 MongoDB Atlas）必填
replicaSet，本地单机可不填，但代码里应允许为空 —— 切环境时不用改逻辑 -
connectTimeoutMS和socketTimeoutMS不是可选项：Docker 容器启动顺序不稳、跨网络调用延迟高时，缺它们会导致 Nest 启动卡住数分钟
常见报错对应的真实原因
这些错误看起来像连接问题，实际几乎全是 URI 构造或参数缺失导致：
-
Authentication failed.→ 没设authSource，或用户名/密码未encodeURIComponent -
Server selection timed out after 30000 ms→ URI 缺replicaSet（副本集场景），或connectTimeoutMS太小 -
DeprecationWarning: current URL string parser is deprecated→ 漏了useNewUrlParser: true - 应用启动成功，但写操作全部失败且无日志 →
authSource错（比如配成mydb而非admin），认证通过但权限不足
最易被忽略的是 authSource 和 replicaSet 的条件存在性 —— 它们在本地开发时完全不需要，但上线后一个都不能少；而 encodeURIComponent 不是“以防万一”，是只要密码含特殊字符就必然要做的动作，没有例外。
