菩提风1. 唯一索引到底解决什么问题：先看没有它时的数据污染现场
做过几年后端的人，基本都遇到过这种场景：用户注册接口被脚本刷了，同一手机号在库里躺了两三条记录；订单系统因为MQ重复投递，支付回调写了两次；导入Excel时源文件里有两行完全一样的身份证号，结果库里出现两个会员ID，后续所有关联业务全部错乱。
这些问题的根源，不是代码逻辑不够严谨，而是数据库层面没有一道“硬约束”。代码里的校验是软的，总有绕过或者并发漏掉的可能。而唯一索引是一种数据库强约束，它保证某个字段或字段组合在整个集合中不出现重复值。在MongoDB里，唯一索引的基本定义就是这样：针对一个或多个字段创建索引，并强制要求这些字段的组合值在集合内唯一。一旦违反，写入或更新操作直接报错，从根源堵住重复数据。
我在项目里一贯的做法是：业务上必须唯一的字段，比如手机号、邮箱、身份证、订单号、设备编号，一律在数据库里建唯一索引。注意，是“数据库约束”层级的唯一，不是“业务代码判断一遍”的唯一。原因很简单，业务代码判断存在之后再插入，中间有一个时间窗，两个并发请求可能同时判断“不存在”，然后同时写入，最终就是两条重复数据。唯一索引没有这个问题，它是存储引擎内部实现的原子性约束，在写入那一刻做检查，并发场景下依然有效。
这一篇专门把MongoDB唯一索引讲透，包括底层怎么实现、有哪几种创建方式、哪些隐藏坑、以及真实项目中怎么用才不踩雷。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 唯一索引的底层实现：存储引擎是怎么“拦截”重复值的
2.1 唯一性检查发生在哪个环节
很多人以为唯一索引是在数据库逻辑层做了一次查询，先查一遍有没有重复，再决定是否写入，其实不是。MongoDB默认的WiredTiger存储引擎，在写入一条文档时，会同时更新索引条目。对于唯一索引，WiredTiger在插入或更新索引条目时，会利用索引自身的键值唯一性来检查冲突。
你可以把唯一索引理解成一本按拼音首字母排列的电话簿，每个名字只能占一个位置。新来一个人要登记时，不是先翻一遍整本书看有没有同名的，而是在他该在的那个字母区间直接确认“这个位置有没有被占”。如果已经被占，就拒绝写入并抛出一个duplicate key错误。这个检查发生在写入路径内部，跟并发无关，天然就是原子的。
这个“直接在键位置检查冲突”的机制，也是唯一索引性能损耗很低的原因。相比先查后写的方案，唯一索引多出来的开销其实很小，尤其是索引本身能覆盖查询时，代价几乎可以忽略。
2.2 唯一索引不是“查询时去重”，而是“写入时拦截”
这里有个容易混淆的点。唯一索引不是对现有数据做去重，而是在写入阶段就拒绝重复。也就是说，如果集合里已经存在重复数据，你再去创建唯一索引，创建过程会直接失败，而不是自动帮你清理数据。
我遇到不止一个同事，在设计阶段忘了加唯一索引，等线上跑了大半年才发现数据重复，这时候再补索引，报错信息一大堆，最后只能写脚本清洗数据。所以最佳实践永远是：业务设计阶段就确定哪些字段必须唯一，第一时间建好唯一索引，不要指望事后补救。
2.3 WiredTiger索引结构对唯一键的影响
WiredTiger的索引默认是一棵B+树变体，内部以索引键值组织。唯一索引要求每个索引键值只能对应一条文档。这里有一个细节：如果你创建的复合唯一索引包含多个字段，那么唯一性校验的是“多个字段的组合值”，而不是单个字段的值。比如对 {userId: 1, skuId: 1} 建唯一索引，它允许出现多个相同userId的记录，也允许出现多个相同skuId的记录，但只要userId和skuId的组合相同，就拒绝写入。
这一点在实际业务中非常常用，比如购物车：同一个用户对同一个商品只能有一条记录；又比如点赞关系：同一个用户对同一篇帖子只能有一条点赞记录。
3. 创建唯一索引的四种方式与实操细节
3.1 mongo shell中创建单字段唯一索引
最基础的操作是给单个字段加唯一索引，命令长这样：
javascript复制db.users.createIndex({ email: 1 }, { unique: true })
这行命令的意思是：在users集合的email字段上创建一个升序唯一索引。创建完成后，任何两条文档如果email字段值相同，第二次写入就会报错。这里需要注意，email字段的类型不同也会影响唯一性判断。MongoDB中，字符串"123"和数字123不是同一个值，所以 { email: "123" } 和 { email: 123 } 可以同时存在。如果希望类型也严格唯一，建议在业务层统一字段类型，或者在写入前做规范化。
3.2 创建复合唯一索引
复合唯一索引的语法是把多个字段放进一个对象里：
javascript复制db.likes.createIndex({ userId: 1, postId: 1 }, { unique: true })
这个索引约束的是组合唯一。同一个userId可以点赞不同的postId，同一个postId也可以被不同的userId点赞，但是某个userId重复点赞同一个postId时，第二次写入会被拒绝。这在设计“关注关系”“收藏关系”“投票记录”这类多对多关联表时几乎是标准配置。
3.3 部分唯一索引：只对满足条件的文档生效
实际业务中，很多时候我们并不希望所有文档都受唯一约束控制。比如用户表里，手机号是选填的，只有填写了手机号的用户才需要保证手机号唯一；没填手机号的用户，这个字段根本不存在或为null，不该影响其他文档。
这时候可以用partialFilterExpression参数：
javascript复制db.users.createIndex(
{ phone: 1 },
{ unique: true, partialFilterExpression: { phone: { $exists: true } } }
)
这样创建出来的索引，只对phone字段存在且值不为null的文档做唯一性约束。没有phone字段的文档，想存多少条都行。这个用法在“选填字段唯一约束”的场景下极其好用。
3.4 稀疏唯一索引：老版本中处理缺失字段的方式
在partialFilterExpression出现之前，MongoDB提供了sparse参数，表示“稀疏索引”——只对包含该字段的文档建立索引条目，不包含该字段的文档不会进入索引。
javascript复制db.users.createIndex({ phone: 1 }, { unique: true, sparse: true })
注意，sparse和partialFilterExpression的核心区别在于：sparse只判断字段是否存在，partial则支持任意查询条件。比如“只有VIP用户的手机号才要求唯一”这种场景，用sparse做不到，必须用partialFilterExpression。新项目建议直接用partialFilterExpression，语义更清晰，灵活性也更高。
3.5 通过驱动和Compass创建
除了mongo shell，主流驱动中也能创建唯一索引。以Node.js驱动为例：
javascript复制await db.collection('users').createIndex({ email: 1 }, { unique: true });
Python的pymongo写法是：
python复制db.users.create_index([("email", pymongo.ASCENDING)], unique=True)
如果你习惯用MongoDB Compass图形化工具，在集合的Indexes标签页点击Create Index，填入字段和选项，勾选Unique即可。Compass的好处是能直观看到索引大小、使用情况，适合不太熟悉命令行的同学。
4. 创建唯一索引时最常见的几个坑与完整排查链路
4.1 坑一：集合里已有重复数据，索引创建直接失败
这是最普遍的情况。向一个已有数据的集合添加唯一索引时，如果数据中存在重复键，createIndex会报错，错误信息大致如下：
code复制E11000 duplicate key error collection: test.users index: email_1 dup key: { email: "test@example.com" }
遇到这种错误，正确的处理步骤是：
- 先查重复数据。用聚合找出重复键：
javascript复制db.users.aggregate([
{ $group: { _id: "$email", count: { $sum: 1 } } },
{ $match: { count: { $gt: 1 } } }
])
-
根据业务规则决定保留哪条。常见策略是保留_id最小的一条，删除其余重复文档，或者给重复文档增加一个后缀字段再清理。
-
清理干净后，再重新执行createIndex。
-
确认索引创建成功后，在应用层补一条日志或告警，确保后续没有新重复数据进入。
4.2 坑二：missing字段与null字段的唯一性语义
MongoDB对“字段不存在”和“字段值为null”的处理方式，容易让人踩坑。在没有指定sparse或partial的情况下，如果文档a没有email字段，文档b的email为null，文档c的email为null，那b和c算不算重复？答案是：算。
因为在MongoDB中，字段缺失和字段值为null，在索引键上会被统一处理为null。也就是说，多个文档要么都没有email字段，要么email都是null，都会被判定为同一个索引键值，从而违反唯一约束，只允许其中一个存在。
这在现实中很常见：用户表给email建了唯一索引，但很多用户注册时没填邮箱，结果只能存一条“没有邮箱”的用户，其他没填邮箱的用户全部写入失败。
解决办法就是在设计时明确：如果某个字段是可选的，又想加唯一约束，必须使用partialFilterExpression，只对实际填写了该字段的文档做唯一性校验。
4.3 坑三：复合唯一索引中部分字段缺失
复合唯一索引也有类似问题。比如给 { userId: 1, email: 1 } 加唯一索引，如果某条文档没有email字段，那么不管它userId是多少，所有“没有email”的文档在索引里的键值都是 { userId: 对应值, email: null }。如果同一个userId出现了两次，且两条记录都没有email，那这两条记录的复合键值就是完全一样的，会违反唯一约束。
如果业务上允许某个关联字段缺失，建议同样加上partialFilterExpression，或者手动给缺失字段填一个不会重复的默认值。
4.4 坑四：索引名重复与隐藏索引
创建索引时如果不指定名称，MongoDB会根据字段名和排序方式自动生成索引名，比如email_1。如果重复创建同名但选项不同的索引，不会直接覆盖，而是会报错，提示索引已存在。比较稳妥的做法是在代码中显式指定name：
javascript复制db.users.createIndex({ email: 1 }, { unique: true, name: "uq_email" })
另外，MongoDB 4.4及以上版本支持隐藏索引(hidden index)。如果你临时想测试“去掉唯一索引”的性能影响，不建议直接drop，可以用隐藏索引先让优化器忽略它，观察一段时间再决定。不过隐藏索引对唯一约束本身还是生效的，它只是查询优化器不选它而已。这一点要特别注意：隐藏唯一索引，唯一性依然保证，别指望用hidden来关闭约束。
4.5 完整排查链路：从报错到定位根因
假设生产环境突然出现大量duplicate key错误，完整的排查思路应该是这样的：
- 先看报错信息中的集合名和索引名，确认是哪个唯一索引被命中。
- 登录MongoDB，用db.collection.getIndexes()查看索引定义，确认约束字段和选项。
- 用聚合查询查出当前集合里该字段的重复分布，判断是存量问题还是新增问题。
- 查看写入日志和应用调用链，确认这段时间是否有并发上涨、是否有重试机制导致同一条消息被处理两次。
- 检查写入逻辑，看是否有“先查后写”这种非原子操作。如果有，把它改成upsert或insertOne捕获error码11000，从而做幂等处理。
- 如果是并发导致，重点分析业务上是否真的需要拒绝重复，还是应该用update + $setOnInsert做幂等写入。
这套排查链路，基本能覆盖绝大多数唯一索引生产事故。
5. 唯一索引在真实业务中的设计取舍与替代方案
5.1 幂等写入：唯一索引不只是“查重工具”
唯一索引最容易被忽略的价值，是帮助实现幂等。以支付回调为例：支付网关可能因为网络抖动，对同一笔订单发送多次回调。如果业务表里没有订单号唯一索引，每次回调都做一次insert，就会产生多笔相同订单号的记录。加上订单号唯一索引后，第二次回调触发E11000错误，应用层捕获到这个错误后，直接当作“已处理”返回成功即可。这样处理，比先查一次再决定是否写入要稳妥得多。
典型代码框架（Node.js）大概是：
javascript复制try {
await orders.insertOne({ orderNo: receivedOrderNo, status: 'PAID' });
} catch (e) {
if (e.code === 11000) {
// 已经处理过，按成功返回
return { success: true, duplicated: true };
}
throw e;
}
这种写法的好处是：没有查询开销、没有竞态窗口、逻辑简单明了。生产环境里我经常推荐用这种模式替代“先查再写”。
5.2 唯一索引不能替代业务状态机
唯一索引解决的是“重复”问题，但解决不了“状态流转错误”的问题。比如订单状态从PAID变成REFUNDED，又变回PAID，只要订单号唯一，这种多次更新本身不会被索引拦截。所以设计时不能因为有了唯一索引，就觉得数据万事大吉：状态校验、版本号、乐观锁这些还是得有。
推荐做法是把唯一约束用于“标识身份”的字段，把状态约束放到应用层或文档结构校验中。一个订单号只对应一条记录，但这条记录自身的状态变迁，属于另一个维度的问题。
5.3 备选方案：哈希字段唯一 vs 天然主键唯一
有一种场景：某个字段非常长，比如很长的URL或文本内容，直接建唯一索引会导致索引体积大、写入性能下降。这时可以引入一个额外的哈希字段，比如用MD5或SHA-256算出固定长度的哈希值，对哈希字段建唯一索引。查询时也用哈希值匹配，这样索引体积小，唯一性也得到保证。
比如文章系统要防止“同内容重复发布”，就可以在写入时计算contentHash字段：
javascript复制db.articles.createIndex({ contentHash: 1 }, { unique: true })
当然这要求应用层保证contentHash计算正确，如果哈希算法发生碰撞，虽然概率极低，但理论上可能误伤。实际选择时，可以结合业务容忍度来决定。
另外，MongoDB自带_id字段天然是唯一索引，只是这个唯一索引不能被删除，也不需要你手动创建。在很多场景下，如果能用_id表达业务唯一性，优先用_id，省去额外索引开销。
5.4 唯一索引与分片集群的边界
如果集合使用了分片，唯一索引有个非常关键的约束：分片集合中，唯一索引的字段必须包含分片键。也就是说，你不能随便挑一个唯一字段建唯一索引，除非这个字段是分片键的一部分，或者是分片键本身。
原因很简单：分片集群中，MongoDB只能在每个分片内部保证唯一性，跨分片的全局唯一需要把唯一索引的键路由到同一个分片才能检查。如果唯一索引字段不包含分片键，写入时无法在单个分片内完成唯一性校验，MongoDB直接拒绝创建索引。
这一点在分片设计阶段就要确定，否则等数据量大了再想改，代价非常大。我的建议是：使用分片集群时，尽量把业务唯一键设计为分片键，或者把分片键作为复合唯一索引的前缀字段。
6. 唯一索引的维护、监控与性能影响
6.1 如何在运行中查看唯一索引的命中情况
MongoDB没有直接提供“唯一索引拦截了多少次重复写入”的计数器，但可以通过查看profile日志和系统异常日志来观察E11000错误出现的频率。如果E11000频繁出现，很可能意味着应用对同一业务标识重复投递，说明上游幂等机制不完善。
更推荐的做法是在应用层统一封装写入函数，捕获error code 11000并打点统计。长期观察这个指标，能够帮助你发现业务是否存在大量重复请求，从而优化发送端逻辑。
6.2 唯一索引对写入性能的影响
唯一索引本质上是每次写入都要额外维护一份索引。跟普通索引相比，它多做了唯一性检查。但正如前面说的，这个检查不是全表扫描，而是B+树上的键值查找，开销非常低。实际线上项目中，单字段唯一索引对写入性能的影响通常在个位数百分比级别，几乎可以忽略。
真正影响性能的是创建索引的过程本身。如果集合数据量很大，createIndex会占用大量资源，可能导致业务卡顿。建议在低峰期创建，或者使用background选项（新版本默认就是后台构建，旧版本需要显式指定）。
6.3 索引选型建议：不是所有字段都适合加唯一索引
我见过一些新手，为了“保险”，给几乎所有字段都加上唯一索引，结果数据稍微有点缺失或类型不一致，写入就到处报错。唯一索引应该是“业务语义上绝对必须唯一”的字段，而不是“通常比较唯一”的字段。比如“用户名”通常是唯一的，但如果业务允许重名，那就不该加。加了之后，后续产品想放开重名限制，还得先drop索引，来回折腾。
判断标准就一句话：这个字段的重复值，是否会导致业务数据无法区分、产生严重错误的关联。如果是，加；如果不是，别加。
7. 最后分享几点实战体会
唯一索引对我来说，是MongoDB设计阶段最需要提前想清楚的约束之一。它比应用层校验可靠得多，也比事后清洗数据成本低得多。我自己的习惯是：新建集合时，第一件事不是想查询有哪些，而是先把唯一字段定下来，建好唯一索引，再进入业务开发。
遇到过最难忘的一次生产事故：客户表没有唯一索引，凌晨的数据同步任务因为网络重试，同一批客户数据被导入了两次，第二天业务方发现好几万条重复客户，最后花了整整一天写脚本合并数据。那之后，我在任何涉及唯一标识的集合里，第一件事就是确认唯一索引是否已经存在。
另外，如果你在已经有重复数据的集合上建唯一索引，不要慌，按照第四节里的聚合查询方法先找出重复项，按业务规则清理，再建索引，整个过程完全可以安全完成。唯一索引不是银弹，但它确实是MongoDB里最便宜、最有效的一道数据质量防线。