maxTimeMS是MongoDB聚合查询的服务端硬性执行时间上限，必须通过链式调用collection.aggregate([]).maxTimeMS(5000)显式传入，仅作用于服务端执行阶段，不涵盖网络延迟或锁等待，设错位置或被socketTimeoutMS优先触发则无效。
聚合查询超时，八成不是网络或连接问题，而是服务端执行卡死——必须用 maxTimeMS 强制中断，否则它会一直占着连接不放。
Node.js 驱动里怎么正确设置 maxTimeMS
这个参数不是配置项，是每个聚合调用必须显式传入的硬性限制。写错位置就完全不生效：
-
collection.aggregate([]).maxTimeMS(5000)—— 正确，链式调用 -
collection.aggregate([], { maxTimeMS: 5000 })—— 错误，Node.js 驱动不认这种写法 - 只在
MongoClient构造选项里设maxTimeMS—— 无效，它不作用于聚合操作 - 和
timeout或socketTimeoutMS混用时，maxTimeMS是服务端计时，优先级更高；但若客户端连都连不上，根本触发不到它
为什么设了 maxTimeMS 还没看到超时日志
常见原因是超时根本没走到服务端：
- 客户端 DNS 解析失败（尤其 Atlas 的
mongodb+srv://），卡在域名解析阶段，maxTimeMS压根没开始计时 -
socketTimeoutMS先于maxTimeMS触发（比如设了socketTimeoutMS=1000、maxTimeMS=5000），错误类型变成MongoNetworkError而非MaxTimeMSExpired - 查询被
system.profile忽略：默认slowms=100，而maxTimeMS=3000的查询若实际跑了 2990ms 就被中断，不会记入慢日志 - 用了
explain("executionStats")测试，但超时后返回的是残缺统计，executionTimeMillis可能为 0 或远低于maxTimeMS，不能当真
查不到慢聚合？先确认是不是真在跑
别急着调参，先看服务端有没有活的长耗时聚合：
- 连上 mongosh，运行
db.currentOp({ "secs_running": { "$gt": 2 } })，筛出op: "command"且ns匹配你集合的条目，看query.$pipeline内容 - 如果
secs_running持续上涨、numYields很低，说明它卡在 CPU 计算（比如$sort没索引、$lookup关联字段没索引） - 如果
waitingForLock: true，可能是写锁阻塞，或$out/$merge在刷盘 - 注意：
maxTimeMS对$out和$merge的写入阶段也生效，但唯一键冲突重试等内部逻辑可能绕过限制
超时只是止血，根因在聚合写法和索引
maxTimeMS 是熔断开关，不是性能解药。真正卡住的点往往藏在管道结构里：
-
$match不在最前？哪怕只差一个$addFields，索引就彻底失效，totalDocsExamined等于集合总数 - 复合索引字段顺序错：查询用
{ a: 1, b: { $gt: 10 } }，却建了{ b: 1, a: 1 }，范围字段不能放最左 -
$lookup的from表没给关联字段建索引，每次 join 都全表扫，maxTimeMS到期前早把连接池占满 - 聚合含
$unwind+ 大数组？文档爆炸后$group内存吃紧，inMemorySort: true直接拉爆 CPU
真正难的从来不是加个超时参数，而是从 db.currentOp() 里捞出那条正在跑的聚合，再用 explain("executionStats") 一层层看 stage 是否走索引、docsExamined 是否合理、有没有意外的内存排序——这些细节一漏，maxTimeMS 就只能反复报错，救不了命。
