MongoDB的聚合管道功能强大，但当同一条管道需要在多个地方引用同一个计算结果，或者需要把外部条件传入管道内部时，直接写死值的方式既不优雅也难以维护。虽然MongoDB官方并没有一个叫$parameters的阶段操作符，但在实际开发和官方文档语境中，参数化聚合通常通过let变量声明、$expr表达式以及lookup的pipeline形式来实现。这篇文章就把这套参数配置机制完整梳理一遍，配合可运行的示例代码，帮你彻底掌握聚合管道的参数化写法。
聚合管道参数化的三种实现方式
在MongoDB中实现参数传递到聚合管道，主要有三种途径。第一种是使用$expr配合查询语句，直接在find或$match中比较两个字段或引用外部值；第二种是在db.collection.aggregate的第二个参数中使用let选项，声明全局变量供管道各阶段引用；第三种是在$lookup阶段内部，通过let为子管道定义变量，再用pipeline形式的子查询引用这些变量。
这三种方式的适用场景各不相同。$expr适合简单的条件比较，比如比较两个文档字段的值；let选项适合把外部计算结果传入管道，避免重复计算；$lookup的let则专门用于集合关联查询时传递关联条件。下面先看一个最基础的$expr用法：
// 比较 orders 集合中 total 与 discount 两个字段
db.orders.find({
$expr: {
$gt: ["$total", "$discount"]
}
})
// 引用外部写死的值作为参数
db.orders.find({
$expr: {
$gt: ["$total", 1000]
}
})
$expr的语法核心是：字段引用用$字段名，变量引用用$$变量名，这是区分普通值和变量的关键。很多初学者把两者混淆，导致查询结果异常却没有报错，这是需要特别注意的。
使用let声明参数变量并在管道中引用
aggregate命令支持第二个参数options，其中let字段可以声明一组变量，这些变量在整个管道的所有阶段都可用。这种方式的优点是参数只声明一次，多处引用，修改时只需改一处。例如我们要查询订单金额大于某个阈值的订单，并按状态分组统计：
db.orders.aggregate(
[
{
$match: {
$expr: {
$gt: ["$total", "$$minTotal"]
}
}
},
{
$group: {
_id: "$status",
count: { $sum: 1 },
totalAmount: { $sum: "$total" }
}
}
],
{
let: {
minTotal: 500
}
}
)
上面的例子中，minTotal就是在let中声明的参数，管道内通过$$minTotal引用。如果minTotal在多个阶段都要用到，这种写法比在每个阶段重复写500要清晰得多。更重要的是，当通过驱动程序执行时，let中的值可以作为变量动态传入，实现了类似SQL预编译语句的效果，既安全又能充分利用索引。
需要注意作用域规则：let声明的变量作用域是整个外层管道，但不会自动传入$lookup的子管道。如果子管道需要这些变量，必须在$lookup内部显式声明。另外，变量名区分大小写，$$MinTotal和$$minTotal是两个不同的变量，拼错时MongoDB会抛出错误的解析错误，提示变量未定义。
$lookup子管道的参数传递配置
$lookup是聚合中最常用的关联查询阶段，从MongoDB 5.0开始推荐使用let加pipeline的简洁形式来传递关联参数。相比早期的localField和foreignField形式，这种方式支持更复杂的关联条件。示例如下：
db.orders.aggregate([
{
$lookup: {
from: "customers",
let: {
orderCustId: "$customerId",
orderTotal: "$total"
},
pipeline: [
{
$match: {
$expr: {
$and: [
{ $eq: ["$_id", "$$orderCustId"] },
{ $gt: ["$$orderTotal", 100] }
]
}
}
},
{
$project: {
name: 1,
level: 1,
_id: 0
}
}
],
as: "customerInfo"
}
}
])
这段代码的关键点在于：外层let中的orderCustId: "$customerId"把当前文档的字段值捕获为变量，注意这里用的是单美元符号，因为是在let定义处引用字段；而在子管道内部引用变量时，必须用双美元符号$$orderCustId。这个细节是最容易出错的地方，单双符号用反了会直接报错或者得到空结果。
另一个实践建议是，$expr中的等值条件在某些版本中无法有效利用索引，如果关联的数据量大，可以考虑在子管道中先做一轮基于索引的普通$match筛选，再用$expr处理涉及变量的部分，这样性能会明显提升。同时，let中的变量可以是任意表达式，包括$add、$cond等运算结果，不限于简单的字段引用。
常见报错与排查思路
参数配置相关的报错主要有三类。第一类是变量未定义，错误信息通常是unknown variable，原因是引用了let中没有声明的变量名，或者拼写不一致，排查时仔细核对变量名的拼写和大小写即可。
第二类是类型不匹配。$expr中比较运算符对类型敏感，比如字符串类型的时间字段和ISODate对象直接比较会得不到预期结果。遇到这种情况可以在let声明时用$toDate或$toLong等转换操作符处理，确保比较双方类型一致。
第三类是版本兼容问题。let作为aggregate第二参数的选项需要MongoDB 5.0以上版本完整支持，$lookup的pipeline形式需要3.6以上。如果环境版本较低，建议先执行db.version确认，再选择合适的参数传递方案。掌握这些规则后，你会发现参数化的聚合管道不仅复用性好，配合驱动程序使用时还能有效防止注入风险，是生产环境中值得优先采用的写法。
MongoDB聚合管道$parameters修改时间：2026-09-06 15:26:34