在MongoDB聚合管道里，字段值的解析规则和普通查询存在明显差异。比如在$project阶段给某个字段赋予一个字符串时，驱动和数据库并不会自动把它识别为常量，而是会尝试按字段路径去解析。这种设计在处理动态字段名时很灵活，但一旦想要输出一个固定字符串、尤其字符串以$开头时，直接书写就会产生歧义甚至报错。$literal字面量表达式正是为消除这类歧义而提供的专用操作符。
一、聚合表达式解析规则与$literal的由来
聚合管道中的$project、$addFields、$set等阶段，接受的是表达式对象。一个字段的值如果写成"PENDING"，MongoDB会把它看成名为PENDING的字段引用，而不是字符串常量。例如下面的管道会把订单文档里原来的PENDING字段提取出来，如果该字段不存在，结果就是缺失，而不是输出字符串PENDING。
db.orders.aggregate([
{
$project: {
orderId: 1,
status: "PENDING"
}
}
])
执行结果中status字段并不是固定值PENDING，而是取决于源文档里是否有一个叫PENDING的字段。很多刚接触聚合管道的开发者会在这里遇到结果为空或字段丢失的问题。如果想输出固定字符串，必须改用表达式对象：{ $literal: "PENDING" }。
更典型的情况是字符串本身以$开头，例如价格标签$9.99。在聚合表达式里，$前缀被保留给字段引用和操作符，直接写"$9.99"会被当成对9.99这个字段名的引用，或者解析失败。$literal会原样返回这个字符串，完全跳过字段路径解析。
二、$literal基础语法与典型用法
$literal的语法非常简洁：{ $literal: <value> }，其中value可以是任意合法的BSON值，包括字符串、数字、布尔、null、数组和内嵌文档。它不会对内部值做任何求值或路径替换，返回值就是传入值本身。
// 示例1：输出固定状态字符串
db.users.aggregate([
{
$project: {
_id: 0,
name: 1,
role: { $literal: "admin" }
}
}
])
运行后，每个用户文档都会得到role: "admin"，与源集合中有没有admin字段无关。再看以$开头的字符串：
// 示例2：输出以$开头的价格标签
db.inventory.aggregate([
{
$project: {
_id: 0,
item: 1,
priceTag: { $literal: "$9.99" }
}
}
])
如果不加$literal，$9.99会被当作字段路径或非法表达式，查询可能直接报错。$literal还能包装数组和内嵌文档，保证它们不会被递归解析。比如要新增一个固定元数据字段：
db.config.aggregate([
{
$addFields: {
meta: { $literal: { env: "prod", debug: false, tags: ["core", "api"] } }
}
}
])
此时meta字段的内容完全按原样返回，即使文档内部出现$符号也不会触发字段引用。$addFields是$set的旧名称，两者行为一致，可以根据MongoDB版本选用。
三、$literal与条件表达式配合
$literal在条件分支中非常有用。$cond、$switch这类操作符的then、else分支同样处于表达式上下文，字符串值如果直接书写，可能被当作字段路径解析。为了保证返回的是固定标记，需要把分支值包装成$literal。
db.products.aggregate([
{
$addFields: {
stockStatus: {
$cond: {
if: { $gte: ["$qty", 100] },
then: { $literal: "充足" },
else: { $literal: "补货中" }
}
}
}
}
])
这段管道根据qty字段的值给每个商品增加stockStatus。then和else分支如果直接写成字符串，在部分MongoDB版本中可能返回字段路径的值，而不是常量。使用$literal后，结果稳定可预期。
$switch分支也一样，每个then分支的字符串常量都建议用$literal包裹。另一个常见场景是$filter、$map中的比较条件：当要比较的阈值是字符串时，为了与字段引用区分，可以用$literal包住阈值。
db.orders.aggregate([
{
$project: {
_id: 0,
orderId: 1,
flaggedItems: {
$filter: {
input: "$items",
as: "item",
cond: { $eq: ["$$item.category", { $literal: "fragile" }] }
}
}
}
}
])
这里$literal让字符串fragile作为比较值参与运算，而不是被解析为字段路径。若比较值是数字或布尔，通常不需要$literal，因为它们本身就是字面量类型；但加上也不会导致错误，只是略显冗余。
四、$literal的边界行为与常见误区
第一个常见误区是认为$literal会递归解析内部文档。实际上它非常“懒惰”，传入什么就返回什么。如果把{ $literal: { total: "$amount" } }写入管道，输出文档中total字段的值是字符串"$amount"，而不是amount字段的数值。这个特性在需要保留原始字符串含$前缀时很有用，但如果你的本意是引用字段，就应该直接写"$amount"，不要用$literal包装。
第二个误区与$match阶段有关。$match使用查询语法而非聚合表达式语法，因此普通等值匹配不需要$literal。例如{ $match: { status: "PENDING" } }中的字符串就是字面量，会直接按值匹配。只有$match内部使用$expr这类聚合表达式时，才可能需要$literal。
第三点需要区分$literal与直接写数字、布尔值。像100、true、null不属于字段路径，因此聚合表达式可以安全地把它们识别为常量。官方文档也提到$literal主要针对可能被解释为字段路径的值，最典型的就是字符串。不过这并不意味着字符串在所有表达式位置都必须加$literal，例如$concat的参数中，空格字符串" "会被当作字面量处理。关键在于判断当前上下文是否会把不带$的字符串解析为字段引用。
性能方面，$literal是原生聚合操作符，由服务端直接处理，不涉及JavaScript引擎，开销可以忽略不计。与其担心性能，更重要的是保证查询语义正确。当管道结果出现字段丢失、意外返回其他字段值或报$前缀解析错误时，优先检查字符串常量是否缺少$literal。
五、综合实战：生成带常量的统计报表
下面用一个订单集合的聚合为例，把$literal和其他阶段组合起来。需求是：从原始订单中筛选已完成订单，导出时增加固定渠道标记，并按渠道统计总金额和订单数。原始文档可能包含orderId、amount、status等字段，没有渠道信息，可以在管道开头用$literal生成。
db.orders.aggregate([
// 第一阶段：筛掉未完成订单
{
$match: {
status: "COMPLETED"
}
},
// 第二阶段：生成固定渠道字段并精简输出
{
$project: {
_id: 0,
orderId: 1,
amount: 1,
channel: { $literal: "web" },
reportType: { $literal: "daily" }
}
},
// 第三阶段：按渠道聚合
{
$group: {
_id: "$channel",
totalAmount: { $sum: "$amount" },
orderCount: { $sum: 1 }
}
},
// 第四阶段：排序
{
$sort: { totalAmount: -1 }
}
])
这段管道先使用$match按查询语法筛选status为COMPLETED的订单，这一层不需要$literal。接着$project新增channel和reportType两个固定字段，如果没有$literal，"web"和"daily"会被当作字段路径，由于原文档中不存在web或daily字段，输出将丢失这两列。最后$group正常引用字段完成统计。
如果报表需要输出一个固定的子文档作为元数据，也可以把整个对象放进$literal。比如在$group之后加一个$set阶段，给所有分组结果统一加上meta信息。这种方式比在应用层循环添加更高效，也能保证每个分组文档的数据结构一致。
MongoDB聚合管道$literal字面量表达式修改时间：2026-10-04 22:57:04