MongoDB的写入操作在遇到唯一索引冲突时，服务端会立即中止当前写入并返回一个错误。尽管不同客户端、驱动或云平台对错误码的封装存在差异，但核心错误信息通常是 E11000 duplicate key error，部分平台会将这类约束冲突标记为 1410。它表示目标集合上存在唯一索引，而本次插入或更新操作尝试写入的键值已经存在，因此被服务端拒绝。理解这个错误的触发链路，不仅有助于快速恢复写入，也能避免因为错误处理不当而引入数据不一致。
一、1410错误码对应的底层约束机制
在MongoDB中，唯一索引的作用是保证索引字段的值在集合范围内不会重复。默认情况下，每个集合的 _id 字段上都会自动创建唯一索引，因此插入相同 _id 的文档一定会触发冲突。除此之外，开发人员还可以通过 createIndex 命令为业务字段单独创建唯一索引，例如邮箱、用户名、订单号等。
唯一索引在底层依赖 B-tree 数据结构，写入时服务端会先在索引中查找目标键是否已经存在。如果找到相同键值，就会返回 duplicate key 错误；如果没有找到，则继续执行写入并同步更新索引结构。这一过程在单节点上是原子的，但在分片集群中，唯一索引需要跨越多个分片进行协调，因此对分片键有严格限制。
db.users.createIndex({ email: 1 }, { unique: true })
创建上述索引后，如果 users 集合中已经存在两条 email 相同的文档，创建索引会直接失败。即便索引创建成功，后续任何插入重复 email 的操作也会被拒绝。这就是 1410 错误最常见的来源：历史数据已经重复，或者应用层在并发场景下重复提交了相同内容。
二、如何快速定位冲突键值与重复文档
遇到 1410 错误时，第一步不是盲目删除索引，而是找出违反唯一约束的具体键值。MongoDB 的错误信息中通常会包含 dup key 字段，直接显示冲突的值。如果错误信息被上层封装后只展示 1410 状态码，可以回到 mongosh 中执行聚合查询，按目标字段分组统计出现次数。
db.users.aggregate([
{ $group: { _id: "$email", count: { $sum: 1 } } },
{ $match: { count: { $gt: 1 } } },
{ $sort: { count: -1 } }
])
这段聚合管道首先按 email 字段分组，计算每个邮箱出现的次数，然后筛选出现次数大于 1 的组，最后按重复次数倒序排列。查出的 _id 就是导致唯一索引冲突的键值，count 表示重复数量。比如返回 { _id: "a@ippipp.com", count: 3 }，说明这个邮箱已经存在三条文档。
如果集合数据量较大，聚合查询可能占用较多内存。可以为分组字段提前创建普通索引，或者在聚合选项中设置 allowDiskUse: true 来允许磁盘临时存储。定位到重复键值后，还需要查看重复文档的完整内容，判断哪些是有效数据、哪些应该被清理。
三、修复唯一索引冲突的几种方案
修复方式取决于重复数据产生的原因和业务容忍度。如果历史数据确实重复，最直接的做法是清理重复文档，只保留一条。例如对于 users 集合，按照 email 去重，保留 _id 最小的一条，删除其余文档。
var duplicates = db.users.aggregate([
{ $group: { _id: "$email", count: { $sum: 1 } } },
{ $match: { count: { $gt: 1 } } }
]).toArray();
duplicates.forEach(function(doc) {
var cursor = db.users.find({ email: doc._id }).sort({ _id: 1 });
var first = true;
cursor.forEach(function(item) {
if (first) {
first = false;
} else {
db.users.deleteOne({ _id: item._id });
}
});
});
上述脚本先找出所有重复邮箱，再对每个邮箱按 _id 升序遍历，保留第一条，删除其余文档。所有删除操作都是针对具体 _id，不会误删其他数据。执行完成后可以重新创建唯一索引，观察是否还报 1410。
如果业务上允许某些文档缺少邮箱字段，可以在创建唯一索引时使用 sparse 选项。稀疏唯一索引只对存在该字段的文档生效，不索引缺失字段的文档，从而避免多条缺少 email 的文档互相冲突。另一种方式是使用 partialFilterExpression 创建部分唯一索引，只对满足过滤条件的文档施加唯一性约束。
db.users.createIndex(
{ email: 1 },
{ unique: true, sparse: true }
)
db.users.createIndex(
{ email: 1 },
{ unique: true, partialFilterExpression: { email: { $exists: true, $type: "string" } } }
)
需要注意，唯一索引的属性不能直接在线修改。如果需要切换为 sparse 或 partial 索引，必须先删除旧索引，再按新属性创建。删除索引前建议先确认没有业务查询强依赖旧索引，否则可能引发查询性能下降。
对于并发场景，单靠应用层先查询再插入并不能完全避免 1410。因为两个请求可能同时查询不到记录，然后先后插入同一条数据，仍然触发唯一索引冲突。更稳妥的做法是把唯一索引作为最终防线，在应用层捕获 duplicate key 异常，并根据业务语义选择重试、更新或返回友好提示。
try {
await collection.insertOne({ email: 'a@ippipp.com' });
} catch (err) {
if (err.code === 11000) {
console.log('duplicate key, handle conflict');
}
}
四、预防1410错误的长效机制
唯一索引冲突本质上是数据幂等性设计不足。要减少这类错误，首先要明确哪些字段在业务上必须唯一，并提前创建唯一索引。不要等到线上出现重复数据后再补索引，否则索引创建过程本身就可能失败。
其次，在批量写入或数据迁移时，建议使用 bulkWrite 或 insertMany 的有序参数控制错误处理。设置 ordered: false 可以让批量操作在遇到个别重复文档时继续执行其他写入，而不是整体回滚。事后统计错误结果，单独处理冲突项即可。
对于分片集群，创建唯一索引时要注意：唯一索引的前缀必须包含分片键字段。如果业务唯一字段与分片键不一致，会无法满足全局唯一约束。此时需要重新评估分片键设计，或者将唯一约束下沉到应用层配合分布式锁实现，但这会增加复杂度。
最后，监控和日志也很重要。可以在驱动层或中间件中统计 duplicate key 错误的发生频率，一旦某类写入持续出现 1410，说明上游可能存在重复提交、消息重放或数据清洗逻辑缺陷。结合告警机制，可以在数据质量恶化前介入处理。
MongoDB故障码1410唯一索引约束冲突修改时间：2026-08-26 02:33:48