MongoDB的聚合管道是数据处理的核心工具，它把数据比作流经一条流水线的原料，每个阶段对数据做一次加工。当我们只想知道符合某个条件的文档一共有多少条时，$count阶段就是这条流水线末端的计数器。它写法简单，但不少初学者容易把它和count方法、$size操作符混淆，也有人因为字段命名不合规而报错。这篇文章会把$count的语法、用法和易错点一次讲清楚。
$count阶段的基本语法与工作原理
$count的语法是整个聚合管道里最简单的之一，它只接受一个参数，就是输出字段的名字。完整写法如下：
db.orders.aggregate([
{
$match: { status: "paid" }
},
{
$count: "totalPaidOrders"
}
])这段查询的含义是：先通过$match筛选出status为paid的订单，再由$count统计这些文档的数量，并把结果放到totalPaidOrders字段中。输出结果是一个单文档，例如{ "totalPaidOrders" : 8374 }。
从原理上看，$count完全等价于$group加$project的组合写法。下面这条聚合查询和上面的$count版本结果完全一致：
db.orders.aggregate([
{ $match: { status: "paid" } },
{ $group: { _id: null, count: { $sum: 1 } } },
{ $project: { _id: 0, count: 1 } }
])MongoDB在内部其实就是把$count翻译成这种形式执行的。理解这一点很重要，因为一旦你知道了等价关系，在遇到$count无法满足的复杂统计需求时（比如按多个字段分组再计数），就可以自然地过渡到$group的写法。$count本质上是$sum计数的简化封装，它只能统计整个管道当前的文档总数，不能带任何附加逻辑。
还有一个细节需要注意：如果管道前面的阶段过滤掉了所有文档，导致$count收到的文档数为零，那么$count不会输出一个值为0的文档，而是不返回任何文档。这一点经常让写分页统计的开发者踩坑，应用层判断时要把空结果当作0来处理，否则容易出现空指针异常。
$count与count、countDocuments的区别对比
除了聚合管道中的$count，MongoDB还有collection.count方法和countDocuments方法可以做计数，三者各有适用场景。
老版本驱动中的count方法直接在集合上执行，不经过聚合框架。它的特点是速度快，因为在某些场景下可以直接读取集合的元数据（比如没有查询条件时直接返回估算值）。但正因为如此，在有查询条件且文档频繁变动时，count返回的可能是近似值，准确性无法保证。新版本的MongoDB驱动已经把count标记为废弃，官方建议迁移到countDocuments。
countDocuments则是基于聚合查询实现的，内部实现就是执行一条包含$match和$count（或等价$group）的聚合管道，因此它返回精确计数。它的调用方式是db.orders.countDocuments({ status: "paid" })，效果等同于前面写的聚合查询。简单来说，countDocuments是$count的便捷封装，适合单一条件计数的场景。
那么什么时候必须直接使用$count阶段？答案是当你需要在一条复杂管道中做计数时。比如先$match再$unwind展开数组，然后$match过滤数组元素，最后统计总数。这种多阶段加工后的计数无法用countDocuments一条命令表达，只能自己组装聚合管道，把$count放在末尾。举个具体例子，统计所有订单中购买过商品编号为101的商品的用户数：
db.orders.aggregate([
{ $unwind: "$items" },
{ $match: { "items.productId": 101 } },
{ $group: { _id: "$userId" } },
{ $count: "userCount" }
])这条查询先展开订单明细，匹配目标商品，再按用户去重，最后统计用户数量。整个链条依赖多个阶段配合，这正是聚合管道$count的价值所在。
另外还有一个$size操作符容易混淆。$size是聚合表达式，用于统计数组字段的元素个数，作用在单个文档上，比如{ $size: "$items" }统计某个订单里有几件商品。而$count统计的是文档数量，作用在集合级别。一个是数组长度，一个是文档条数，概念完全不同。
实际场景示例与常见错误排查
下面通过一个分页场景完整演示$count的用法。分页列表页通常需要两个数据：当前页的数据和符合条件的总记录数。总记录数不能只统计当前页，必须基于完整的筛选条件计算。常见的做法是先执行带$count的管道拿总数，再执行带$skip和$limit的管道拿数据：
// 第一条查询：统计总数
const totalResult = await db.collection("orders").aggregate([
{ $match: { status: "paid", createTime: { $gte: start, $lte: end } } },
{ $count: "total" }
]).toArray();
const total = totalResult.length > 0 ? totalResult[0].total : 0;
// 第二条查询：取当前页数据
const list = await db.collection("orders").aggregate([
{ $match: { status: "paid", createTime: { $gte: start, $lte: end } } },
{ $sort: { createTime: -1 } },
{ $skip: (page - 1) * pageSize },
{ $limit: pageSize }
]).toArray();注意代码中对空结果做了防护，当totalResult为空数组时直接取0，这呼应了前面提到的$count零结果不返回文档的特性。
使用$count时最常见的报错是字段名不合法。$count的参数必须是合法的文档字段名，不能以$开头，不能包含点号，也不能是空字符串。例如写成{ $count: "$total" }会直接报错，因为字段名带了$前缀。如果写{ $count: "a.b" }同样会失败，因为点号在MongoDB中代表嵌套路径。此外，$count的阶段值必须是字符串，写成数字或对象都会导致解析失败。
性能方面，计数查询的快慢主要取决于$match阶段能否命中索引。如果按status和createTime两个字段筛选，最好建立复合索引{ status: 1, createTime: -1 }，这样$match可以用索引扫描代替全集合扫描，计数速度会有数量级的提升。可以用explain方法查看执行计划，确认是否走了IXSCAN而不是COLLSCAN。对于数据量极大且不需要精确值的场景，还可以考虑estimatedDocumentCount，它读取集合元数据，速度极快，但只适合无条件计数。
最后总结一下选型建议：单一条件的精确计数用countDocuments最省事；需要在复杂管道末端统计文档数就用$count阶段；统计数组元素个数用$size；无条件的快速估算用estimatedDocumentCount。把这四者的边界分清楚，计数相关的查询基本不会再出问题。
MongoDB聚合管道$count计数MongoDB count修改时间：2026-09-03 05:58:38