事务失效首要检查驱动版本与MongoDB服务端版本是否匹配，因4.0+副本集、4.2+分片集群事务依赖wire protocol协议升级；版本错配会导致startTransaction()静默失败或抛MongoClientException。
事务失效直接看驱动版本是否匹配 MongoDB 服务端版本
MongoDB 驱动不是“越新越好”，而是必须与服务端版本的事务协议对齐。4.0+ 副本集事务、4.2+ 分片集群事务，背后是 wire protocol 的协议升级。如果驱动版本过高（如 v5.x）连 4.0 服务端，或过低（如 v3.4）连 4.2，startTransaction() 可能静默失败或抛出 MongoClientException 而非明确的事务错误。
- Node.js 驱动：v4.0+ 支持 4.0+ 事务；v3.6+ 是最低兼容线，但不支持 4.2 的分片事务
- Java 驱动：v4.3+ 才完整支持 4.2 分片事务；v3.12 仅支持 4.0 副本集事务
- PyMongo：v4.0+ 对应 MongoDB 4.0+；v3.12 不识别
maxCommitTimeMS等 4.2 新参数
执行 npm list mongodb 或 pip show pymongo 确认实际加载版本，注意子依赖可能被其他包锁死——比如某个日志库间接拉了旧版驱动。
连接字符串里漏掉 ?replicaSet=rs0 就等于没开事务开关
事务只在副本集或分片集群中有效，单节点连接（mongodb://localhost:27017）下 startSession() 能成功，但 startTransaction() 会立即失败或降级为普通操作。驱动不会报错，只会跳过事务上下文。
- 必须用副本集格式：
mongodb://host1:27017,host2:27017/?replicaSet=rs0 - 连接后验证：
db.adminCommand({ isMaster: 1 })返回中必须有setName字段 - Java 驱动额外检查：
MongoClient.getClusterDescription().getType()应返回REPLICA_SET
本地开发常误用 Docker 单节点容器跑事务逻辑，实际环境却连的是真实副本集——这种环境差异最容易导致“线下正常、线上失效”。
session.startTransaction() 后没传 session 到每个操作，事务就形同虚设
事务原子性完全依赖 session 实例的传递。每个 insertOne()、updateOne() 必须显式传入同一 session 对象，否则操作脱离事务上下文，变成独立提交。
- 错误写法：
collection.insertOne(doc)（没传 session） - 正确写法：
collection.insertOne(doc, { session }) - Node.js 中容易忽略 callback 或 Promise 链中断导致 session 丢失
- Java 中若用
withTransaction()辅助方法可规避手动传参，但需确保 lambda 内所有操作都走同一个ClientSession
PyMongo 示例里常被复制粘贴却删掉 { session } 参数，这是最隐蔽的“事务假成功”来源。
升级驱动后 serverSelectionTimeoutMS 触发早于事务初始化，掩盖真实问题
新版驱动默认更激进地做服务器发现和健康检查。如果副本集配置未同步（比如仲裁节点未上线、hosts 列表含已下线节点），startSession() 可能卡在 server selection 阶段，超时后抛 MongoServerSelectionError，根本到不了事务逻辑。
- 先确认副本集状态：
rs.status()查看members[n].stateStr是否全为PRIMARY/SECONDARY - 临时调大超时：
?serverSelectionTimeoutMS=60000排除网络抖动干扰 - 禁用自动发现测试：
?directConnection=true（仅限单节点调试，勿用于生产）
这个阶段的失败不报事务相关关键词，容易误判为代码逻辑问题，其实连事务入口都没摸到。
