在MongoDB分片集群中运行多文档事务时，错误码1820是一个绕不开的坎。它通常表现为事务被拒绝执行，错误信息里带着“Transaction involves multiple shards”之类的提示。很多开发者第一次遇到这个错误时都会困惑：明明单机副本集上一切正常，为什么一上分片集群就报错？答案埋藏在MongoDB分片集群的架构骨子里——分片间的数据分散存储，而多文档事务要求原子性，这两者之间存在着天然的紧张关系。理解错误码1820的完整含义，是从容面对分片集群事务的前提。
一、错误码1820的典型报错与触发场景
设想一个在线购物平台，使用分片集群存储用户和订单数据。假设集合users的分片键是userId，集合orders的分片键是orderId。某天，业务需要在一次事务中同时更新用户状态和订单状态，于是写下了类似下面的代码：
const session = db.getMongo().startSession();
session.startTransaction();
try {
db.users.updateOne(
{ _id: "user_1001" },
{ $set: { status: "vip" } }
);
db.orders.updateOne(
{ orderId: "order_2001" },
{ $set: { status: "paid" } }
);
session.commitTransaction();
} catch (err) {
print("Error code: " + err.code + ", message: " + err.message);
session.abortTransaction();
}
这段代码在副本集环境的MongoDB中运行没有问题，但在分片集群上执行时，很容易触发错误码1820。原因在于，第一个updateOne的查询条件是_id，而users集合的分片键是userId，MongoDB无法从_id推断出文档位于哪个分片；第二个updateOne虽然使用了分片键orderId，但执行计划要求第一个操作和第二个操作可能落到不同的分片节点。由于事务中只要存在一个未能定位到分片的写操作，或者事务涉及的文档分散在不同分片，MongoDB就会直接抛出错误码1820。
更直接的触发场景是：在事务中使用一个不包含完整分片键的查询条件去更新文档。例如分片键是{userId: 1}，但更新条件只写了{age: 18}，这会导致MongoDB需要向所有分片广播路由请求，才能找到目标文档。在多文档事务中，这种广播操作无法与事务的原子性约束共存，因此错误码1820会被立即触发。还有一种情况是事务内连续插入了两个分片键范围不同的新文档，由于插入操作必须知道该插入到哪个分片，而这两个文档可能去往不同分片，同样会报错。
值得注意的是，错误码1820并非只在写操作中才出现。如果事务内的读操作使用了不带分片键的查询条件，也可能导致跨分片数据扫描，某些版本的MongoDB会拒绝这类读操作。官方文档指出，分片集群上的多文档事务必须满足一个硬性条件：事务内涉及的所有读写操作都必须路由到同一个分片。而这个路由决策完全依赖于分片键。所以，错误码1820本质上是对“事务跨分片”行为的一种防御性报错，提醒开发者违反了这个基本约束。
二、为什么分片集群限制多文档事务跨分片
要理解这个限制的根源，需要从分布式事务的实现机制谈起。一个多文档事务在MongoDB中会分配一个事务号，写操作会先记录到节点的oplog里，当提交事务时，所有写操作必须被全部持久化并复制到从节点，整个过程要保证原子性。在副本集模式下，这个事务的参与者只有同一副本集内的若干节点，协调相对简单。但到了分片集群，数据被切成多个块分散在不同分片上，如果事务跨越这些分片，就需要有一个协调者同时调度多个分片的资源，完成两阶段提交。MongoDB虽然支持分布式事务，但跨分片事务的开销极其可观：网络通信翻倍、锁竞争加剧、故障恢复的复杂度也会上升。
一个更实际的问题是死锁风险。当多个事务各自持有一个分片上的锁，又同时去申请另一个分片上的锁时，必然产生循环等待。MongoDB的锁机制在单节点内可以通过有向无环图检测突破，但跨节点的死锁检测需要全局锁表，这会让性能雪上加霜。所以，MongoDB从设计层面上就限制事务不能跨分片，只允许在同一个分片内进行多文档操作。错误码1820就是这个限制的外在体现，它在事务开始时就已经禁止了跨分片的可能性，从源头避免了上述复杂问题。
另一个关键因素是分片键的不可变性。一旦集合启用了分片，分片键的值就决定了文档在物理存储上的位置。如果允许跨分片事务，那么在某些场景下需要移动文档到其他分片以完成事务，这又会造成分片键的变动，进而引发数据分布的不均衡。MongoDB为了保证分片集群的稳定性，强制要求事务中的文档必须位于同一个分片内，且分片键值不能在事务中被修改。这看似是一种限制，实则是保证集群整体性能和一致性的重要手段。理解了这个设计动机，就会明白错误码1820不是Bug，而是一种保护机制。
三、排查错误码1820的实用步骤
遇到错误码1820时，不要急着修改代码，先按以下步骤定位问题根源。第一步，用sh.status()检查集合的分片配置，确认分片键的字段名和方向。只有分片键在事务的更新或删除条件中被完整包含，MongoDB才能将操作路由到正确的分片。第二步，检查事务中的所有读写操作，分别列出每个操作使用的查询条件，判断它们是否都携带了完整分片键，且最终是否映射到了同一个分片范围。这里要注意，即使每个操作都带了分片键，如果这些分片键落在不同分片，事务依然会被拒绝。
// 查看分片集合信息 sh.status() // 查看某个集合的分片键 db.printShardingStatus(true)
假设users集合的分片键是{userId: 1}，下面的代码会触发错误码1820，因为更新条件中没有userId：
session.startTransaction();
try {
db.users.updateOne(
{ _id: "user_1001", status: "normal" },
{ $set: { status: "locked" } }
);
session.commitTransaction();
} catch (e) {
print(e.code + " | " + e.message);
}
要修复这个报错，必须把userId加进查询条件，例如：
session.startTransaction();
try {
db.users.updateOne(
{ _id: "user_1001", userId: "user_1001", status: "normal" },
{ $set: { status: "locked" } }
);
session.commitTransaction();
} catch (e) {
print(e.code + " | " + e.message);
}
在代码中，_id通常等于userId，所以可以顺势把userId也写入查询条件，让路由信息完整。但如果分片键和_id不一致，则必须使用独立的分片键字段。此外，还可以通过MongoDB的日志分析错误具体发生在哪一步操作上。日志中通常会记录是哪个集合、哪个操作导致了1820，根据日志中的集合名和操作类型，能更快定位到事务函数中对应的代码块。
四、设计上的规避策略与最佳实践
既然不能跨分片事务，那么在设计数据模型时就要下意识地避开这种需求。最常用的策略是“按分片键聚合相关数据”。以电商业务为例，如果用户的个人资料、订单和钱包余额需要保证一致性，就可以把三者放在同一个数据库中，并统一使用userId作为分片键。这样，针对同一个用户的所有读写操作，都会落在同一个分片上，事务自然就不会跨分片了。具体做法是在创建集合时显式指定分片键：
// 为shop数据库启用分片
sh.enableSharding("shop")
// 以userId作为分片键
db.createCollection("users", { shardKey: { userId: 1 } })
db.createCollection("orders", { shardKey: { userId: 1, orderId: 1 } })
sh.shardCollection("shop.users", { userId: 1 })
sh.shardCollection("shop.orders", { userId: 1, orderId: 1 })
这里将orders的分片键设为复合键{ userId: 1, orderId: 1 }，这样订单首先按用户分割，同一个用户的所有订单都会存储在同一分片上。当事务需要同时更新用户和该用户的订单时，只要查询条件里带上userId，所有操作就能在一个分片内完成。注意，复合分片键的字段顺序很重要，第一个字段必须是业务上高频关联的实体ID。
如果业务确实无法通过数据聚合消除跨分片依赖，另一个思路是把事务拆分成非事务的异步流。例如，在创建订单时先插入订单记录，然后通过消息队列发送一个“支付成功”事件，由下游消费者去更新用户状态。这种异步方案牺牲了强一致性，换来了更高的吞吐量，但在金融交易等强一致性场景下要慎用。更好的替代方式是使用MongoDB的变更流（Change Streams）+ 补偿机制，用最终一致性来换取跨分片操作的可行性。
还有一种容易被忽略的实践是：在事务内不要修改分片键的值。即使你的事务只针对一个分片，但如果过程中修改了分片键字段，MongoDB会认为数据需要迁移到另一个分片，这同样会触发错误码1820。所以在设计文档时，最好把分片键设为不可变字段。如果业务上确实需要修改分片键，应该先删除原文档，再插入新文档，并且不要在事务内进行这两个操作。对于事务内的大小限制也要注意，一个事务最多只能操作1000个文档，这条限制同样适用于分片集群。
最后，请记住错误码1820是分片集群事务的硬边界。与其试图绕过它，不如从架构上接受它。合理设计分片键、把相关数据聚拢、用异步补偿替代强一致性事务，这些才是根本的解决之道。在应用层做好错误捕获与重试机制，也能在偶然出现路由配置错误时快速响应。如果你在设计阶段就遵循“单分片事务”的原则，错误码1820基本不会出现，整个分片集群的稳定性也会大幅提升。