MongoDB中存储数组字段非常常见，一个订单文档里可能包含十几条商品明细，一个用户文档里可能挂着多个收货地址。当需要对这些数组元素做统一处理时，逐条遍历更新既慢又容易出错。聚合管道提供的$map操作符正好解决这个问题，它能像编程语言里的map函数一样，对数组中每个元素执行指定的表达式，返回一个转换后的新数组。本文将从语法、实战案例、常见坑点三个层面展开讲解。
$map操作符语法与参数详解
$map的基本语法结构如下：
{
$map: {
input: <数组表达式>,
as: <变量名，可选，默认为this>,
in: <针对每个元素的表达式>
}
}
三个参数里，input指定要处理的数组，可以是一个字段引用，也可以是任意返回数组的表达式；as定义元素变量的名字，在in表达式中通过两个美元符号加变量名来引用，比如$$item，如果不写这个参数，默认用$$this访问当前元素；in是转换逻辑，每个元素都会执行一遍这个表达式，结果按顺序组成新数组。
有一个容易忽略的细节：$map不会修改原文档，它只是生成新数组，所以通常要配合$addFields或$project把结果写回字段。另外，如果input不是数组或者为不存在字段，$map会直接报错，这一点和普通编程语言里对null调用map会抛异常很相似，实际使用时建议先用$ifNull兜底。
实战案例：订单明细金额计算与字段格式化
假设有一个订单集合，文档结构如下：
{
_id: 1001,
items: [
{ name: "键盘", price: 299, count: 2 },
{ name: "鼠标", price: 129, count: 3 }
]
}
需求是给每个商品计算小计金额，并且把商品名转成大写。用$map实现的聚合语句如下：
db.orders.aggregate([
{
$addFields: {
items: {
$map: {
input: "$items",
as: "item",
in: {
name: { $toUpper: "$$item.name" },
price: "$$item.price",
count: "$$item.count",
subtotal: { $multiply: ["$$item.price", "$$item.count"] }
}
}
}
}
}
])
执行后每个元素都会多出一个subtotal字段，商品名也统一变成大写。注意in里面的表达式返回的是一个完整对象，也就是说元素的输出结构完全由你决定，可以保留原字段、增加新字段，也可以只挑出需要的字段，等于顺带做了一次结构重塑。
再看一个条件映射的例子。如果想对价格超过200的商品打九折，可以在in里嵌套$cond：
db.orders.aggregate([
{
$addFields: {
items: {
$map: {
input: "$items",
as: "item",
in: {
name: "$$item.name",
count: "$$item.count",
price: {
$cond: [
{ $gt: ["$$item.price", 200] },
{ $multiply: ["$$item.price", 0.9] },
"$$item.price"
]
}
}
}
}
}
}
])
这种写法把遍历和条件判断压缩在一个阶段完成，避免了先$unwind展开再$group回聚的繁琐流程，性能上也更省，因为$map全程在单文档内完成，不产生额外的中间文档。
$map与$unwind、$filter、$forEach的选择
很多人分不清什么时候用$map，什么时候用其他数组操作符。核心区别在于：$map是转换，元素个数不变，只是每个元素的值或结构变了；$filter是过滤，元素个数可能减少，但元素本身不变；$unwind是拆解，把数组拆成多条独立文档，适合后续做跨文档统计。
举个组合场景：先过滤掉数量为0的商品，再对剩下的商品计算小计。两个操作符可以嵌套使用：
db.orders.aggregate([
{
$addFields: {
items: {
$map: {
input: {
$filter: {
input: "$items",
as: "item",
cond: { $gt: ["$$item.count", 0] }
}
},
as: "item",
in: {
name: "$$item.name",
subtotal: { $multiply: ["$$item.price", "$$item.count"] }
}
}
}
}
}
])
至于forEach，那是JavaScript层面的方法，只能在$where或客户端脚本里用，性能差且不推荐。如果目标是把转换结果永久写入数据库，聚合管道的输出可以接$merge或者$out，直接批量回写集合，比逐条update的效率高出一个量级。
还有两点经验值得注意。第一，处理可能为空的数组字段时，用input: { $ifNull: ["$items", []] }做保护，否则管道会在半路报错中断。第二，嵌套数组需要多层$map逐层展开处理，变量名不要重复，外层叫item、内层就叫sub，避免$$item引用错层导致结果异常。掌握这些细节后，大部分数组变换需求都能用一个聚合阶段干净利落地解决。
MongoDB聚合管道$map操作符数组转换修改时间：2026-09-09 23:20:34