MongooseModule.forRoot()会阻塞启动，因其内部调用mongoose.connect()并默认启用bufferCommands: true和connectTimeoutMS: 30000，但不自动降级或超时退出，导致NestJS应用在MongoDB不可达时卡住30秒后报错；推荐改用forRootAsync配合useFactory异步连接并返回空URI实现非阻塞初始化。
连接阻塞不是代码写错了，而是 MongooseModule.forRoot() 默认同步等待连接建立完成，一旦 MongoDB 服务不可达或网络延迟高，NestJS 应用就会卡在启动阶段，根本起不来。
为什么 MongooseModule.forRoot() 会阻塞启动
这个方法内部调用 mongoose.connect() 并默认启用 bufferCommands: true 和 connectTimeoutMS: 30000，但它**不会自动降级或超时退出**——只要连接没成功，它就一直等，直到超时（30秒）或失败抛错。而 NestJS 的模块初始化是串行的，前一个模块没 ready，后续模块和 HTTP 服务根本不会启动。
- 本地开发时 MongoDB 没开，
npm run start会卡住 30 秒后报错Server selection timed out after 30000 ms - Docker 环境中 MongoDB 容器启动慢于 NestJS 容器，也会触发同样问题
- 即使加了
retryAttempts: 0，也不代表跳过连接检查，只是不重试
用 useFactory + 异步连接绕过阻塞
核心思路：把连接逻辑从模块初始化阶段移出，改由服务按需触发，并允许失败不中断启动。推荐在 AppModule 中用 useFactory 替代直连字符串：
import { MongooseModule } from '@nestjs/mongoose';
import * as mongoose from 'mongoose';
<p>MongooseModule.forRootAsync({
useFactory: async () => {
try {
await mongoose.connect('mongodb://localhost:27017/mydb', {
connectTimeoutMS: 5000,
socketTimeoutMS: 5000,
});
return { uri: 'mongodb://localhost:27017/mydb' };
} catch (err) {
console.warn('MongoDB connection failed, proceeding without DB:', err.message);
return { uri: '' }; // 空 URI 让 Mongoose 不再尝试连接
}
},
});
- 必须显式设置
connectTimeoutMS和socketTimeoutMS，否则仍可能卡满默认 30 秒 - 返回空
uri是关键——MongooseModule遇到空字符串会跳过连接，但模块本身仍能加载 - 后续业务逻辑里可通过
mongoose.connection.readyState判断是否已连上
连接失败后如何安全使用 Model
不能假设 @InjectModel 总是可用。每次数据库操作前都要检查连接状态，否则会直接抛 Topology was destroyed 或 Cannot read properties of undefined：
async findAll() {
if (mongoose.connection.readyState !== 1) {
throw new Error('MongoDB not connected');
}
return this.model.find().exec();
}
-
readyState === 1表示已连接且可读写；0是断开，2是连接中，3是断开中 - 不要在构造函数里就调用
find()，因为此时连接很可能还没准备好 - 如果项目允许离线运行（如 CLI 工具或部分管理后台），建议封装一层 fallback 逻辑，比如返回 mock 数据或抛自定义异常
真正麻烦的不是连不上，而是连不上时应用还硬扛着不起来——这会让健康检查失败、K8s Pod 反复重启、CI 流水线卡死。把连接从“启动强依赖”变成“运行时可选能力”，才是现代服务编排下的务实做法。
