$addFields 不修改原始文档，仅在聚合中临时添加字段；要持久化需配合 updateMany() 等写操作，且管道中须用数组包裹、正确引用字段，空值和覆盖逻辑需显式处理。
为什么 $addFields 不会修改原始文档
$addFields 是聚合管道阶段，它只在当前聚合上下文中生成新字段，不触碰集合里的原始数据。你看到的“追加”只是临时结果——就像用 SELECT 加了个计算列，不影响磁盘上存的 BSON 文档。
常见误解是把它当 update() 用，结果跑完聚合啥也没变，还纳闷字段去哪了。
怎么让 $addFields 的结果真正落地
要持久化新增字段，必须配合写操作。最直接的方式是用 updateMany() + 聚合管道（MongoDB 4.2+ 支持）：
- 不能只写
{ $addFields: { status: "active" } }，必须包在数组里，作为updateMany()的第二个参数 - 管道里只能引用当前文档字段，不能用变量或外部值（除非用
$let配合） - 如果字段名已存在，
$addFields会覆盖原值；想跳过已有字段得先用$cond判断
db.users.updateMany(
{ lastLogin: { $exists: true } },
[ { $addFields: { hasLoginHistory: true } } ]
)
$addFields 在 update 中的典型陷阱
容易出错的地方不是语法，而是字段引用逻辑：
- 在
updateMany()的聚合管道中，$$ROOT指向整个匹配文档，但别误写成$ROOT（那是错误语法） - 如果想基于某个子字段计算新值，比如
profile.age，直接写$profile.age会报错，必须用$profile.age或嵌套$getField（4.4+） - 空值处理不加判断：若
score可能为null，{ grade: { $switch: { ... } } }会返回null，而不是你期望的默认值
替代方案：什么时候不该用 $addFields 做追加
如果目标只是给所有文档加一个固定值字段，用 $set 更轻量、更易读：
db.users.updateMany({}, { $set: { source: "import_v2" } })
$addFields 的价值在于动态计算，比如：
- 拼接字段：
{ fullName: { $concat: ["$firstName", " ", "$lastName"] } } - 条件赋值：
{ category: { $cond: [{ $gt: ["$sales", 10000] }, "premium", "basic"] } } - 时间转换：
{ createdAtDate: { $dateToString: { format: "%Y-%m", date: "$createdAt" } } }
真正复杂的是字段依赖链和空值传播——比如从 address.zip 推导 region，但 address 可能缺失，这时光靠 $addFields 不够，得前置 $ifNull 或 $replaceRoot 整形。
