Node.js操作MongoDB事务90%报错源于未正确创建和传入ClientSession：必须先await client.connect()再调client.startSession()，所有事务操作均需显式传入{session}选项，且仅支持副本集或分片集群。
Node.js 操作 MongoDB 事务报错，90% 是因为没正确创建和传入 ClientSession —— 不是驱动不支持，而是 session 对象根本没建立或没透传到每一步操作里。
为什么 client.startSession() 不能省略
事务不是“打开开关”就能用的功能，它依赖一个显式的会话对象。MongoDB 驱动要求你必须先调用 client.startSession() 创建 ClientSession 实例，否则所有带事务语义的操作（比如 withTransaction()、insertOne({ session })）都会失败。
- 错误现象：
TypeError: Cannot read property 'startTransaction' of undefined或TopologyDescription not connected - 常见误写：直接在
db.collection('x').insertOne(...)前加await session.withTransaction(...)，但session变量压根没定义 - 关键约束：
client.startSession()必须在await client.connect()之后调用；否则会因 client 未就绪而静默失败 - session 不能复用：一次事务结束后，该
session对象即失效；要再开事务，必须session.endSession()后重新client.startSession()
withTransaction() 里所有操作都得带 { session } 参数
MongoDB 不会自动把 session “注入”到 collection 方法里。每个涉及事务的数据操作，都必须显式传入 { session } 选项，否则它就变成普通非事务操作，事务上下文直接断裂。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 正确写法：
await db.collection('orders').insertOne({ status: 'pending' }, { session }) - 错误写法：
await db.collection('orders').insertOne({ status: 'pending' })（漏掉{ session }） - updateOne、deleteOne、findOneAndUpdate 等全部同理，缺一不可
- 注意：回调函数必须返回 Promise；如果里面用了
async/await却没return，事务会提前 commit，后续操作被丢弃
本地开发时事务直接报 Transaction numbers are only allowed on a replica set member...
这不是代码问题，是 MongoDB 服务端限制：单机 mongod 进程不支持事务，只允许副本集（replica set）或分片集群（sharded cluster）。
- 错误日志典型内容：
Transaction numbers are only allowed on a replica set member or mongos - 最轻量解决方式：启动时加
--replSet rs0参数，例如：mongod --replSet rs0 --port 27017 --dbpath /data/db - 启动后连上执行
rs.initiate()，等状态变成"ok" : 1就可用了 - 别试图绕过——改驱动、降版本、换连接字符串都无效；这是服务端硬性校验
UnknownTransactionCommitResult 错误怎么安全重试
这个错误表示事务已提交，但客户端没收到确认响应（比如网络中断、proxy 超时）。它不在官方 TransientTransactionError 列表里，所以不能靠 errorLabels.includes("TransientTransactionError") 判断。
- 必须精确匹配
error.name === "UnknownTransactionCommitResult" - 推荐退避策略：第 1 次失败后
await new Promise(r => setTimeout(r, 100))，第 2 次300ms，第 3 次直接抛出原始错误 - 不要在
withTransaction()外层套自己的重试循环——这会导致重复执行整个事务逻辑，可能引发双写 - 真正需要重试的是 commit 阶段，而
withTransaction()内部已经处理了多数 transient 场景；UnknownTransactionCommitResult是少数需手动干预的例外
最容易被忽略的一点：事务内所有操作必须发生在同一个数据库里。跨库事务（比如 db1.orders 和 db2.inventory）无论 session 怎么传、replica set 怎么配，MongoDB 都会拒绝执行——错误信息可能很隐晦，但根源就在这里。
