跨分片事务失败主因是分片间版本与配置不一致：mongodb小版本（含补丁号）须完全统一，readconcern必须全为"majority"且enablemajorityreadconcern=true，否则prepare阶段静默失败。
分片版本和配置必须完全一致
跨分片事务失败，大概率不是代码写错了，而是参与事务的分片之间版本或配置不一致——尤其是 readConcern 级别和 MongoDB 小版本号（含补丁号）。哪怕只是 5.0.15 和 5.0.20 混用，就可能在 prepare 阶段静默失败，报 TransactionTooOld 或 UnknownTransactionCommitResult。
实操建议：
- 逐个连接每个 shard 的
primary，执行db.version()，比对完整版本字符串（如"5.0.20"），不能只看主版本 - 执行
db.runCommand({ buildInfo: 1 })，检查gitVersion字段是否全集群一致；若出现"dirty"后缀，说明是非官方构建包，风险极高 - 确认所有 shard 启动时都带
--enableMajorityReadConcern参数，或配置文件中enableMajorityReadConcern: true - 检查
db.runCommand({ getCmdLineOpts: 1 })返回的parsed.enableMajorityReadConcern是否为true
readConcern 必须全为 majority 且可支撑
MongoDB 跨分片事务强制要求所有分片启用 readConcern: "majority"，且对应副本集必须实际能提供 majority 读能力。如果某个分片 oplog 太短、成员状态异常，或未完成初始同步，就会在 prepare 阶段拒绝加入事务，mongos 收到类似 ReadConcernMajorityNotAvailableYet 或 NotMasterOrSecondary 的错误。
实操建议：
- 在每个 shard 副本集上运行
rs.status()，确保所有成员stateStr是PRIMARY或SECONDARY，且optimes.lastCommittedOpTime与主节点接近 - 避免在分片中混用仲裁节点（
arbiterOnly: true）——仲裁节点无法参与多分片事务的数据操作，会导致写入直接中止 - 禁用内存存储引擎（
inMemory）的分片：这类分片默认writeConcernMajorityJournalDefault: false，不支持事务
网络延迟下心跳与事务超时必须协同调优
跨地域或高延迟网络中，默认参数会让事务卡在 commitTransaction 阶段超时回滚，报 "context deadline exceeded" 或 "Transaction is not in progress"。这不是事务逻辑问题，而是心跳检测跟不上真实 RTT，驱动误判节点失联，导致会话丢失。
实操建议：
- 将
heartbeatFrequencyMS设为2000（2 秒），electionTimeoutMillis设为10000（10 秒），保持 1:5 比例；跨 region 场景可设heartbeatFrequencyMS=5000，但electionTimeoutMillis必须 ≥30000 - 服务端调大
transactionLifetimeLimitSeconds至180（默认 60），覆盖端到端抖动周期 - 客户端务必用外层
context.WithTimeout统一控制事务生命周期，不要依赖驱动默认超时 - 避免在连接字符串里漏掉
?replicaSet=xxx或连错单节点地址——事务必须走 replica set 或 mongos，单节点不支持
Java 客户端会话与操作必须严格绑定
Java 驱动里事务失效，常因会话管理松散：每次操作新建 ClientSession、没传会话进 withTransaction 回调、或事务内用了不支持的操作（如 createCollection），都会让事务原子性崩塌。
实操建议：
- 事务必须用
client.withTransaction()回调 API 启动，不能手动startTransaction()+commitTransaction() - 回调内所有数据库操作（
insertOne、updateMany等）必须显式传入同一个session实例 - 事务内禁止执行 DDL 操作（
createCollection、dropIndex等），只允许 DML - 确认驱动版本匹配服务端：MongoDB 4.2+ 分片事务需 Java Driver 4.3+，且
retryWrites=true（默认开启）不能关闭
