$replaceWith 是 $replaceRoot 的安全替代方案，推荐优先使用；它支持任意表达式、可处理空值/数组/字面量，而 $replaceRoot 要求输入必须为对象，否则报错“newRoot must be an object”。
$replaceWith 和 $replaceRoot 都会替换文档根节点，但行为和容错能力完全不同
直接结论：$replaceWith 是 $replaceRoot 的安全替代方案，推荐在所有新聚合管道中优先使用。它不强制要求输入必须是对象，能处理空值、缺失字段、数组甚至字面量，而 $replaceRoot 在遇到非对象值时会立即报错 "newRoot must be an object"。
为什么 $replaceRoot 容易出错？
$replaceRoot 对输入表达式极其严格：
- 如果
$replaceRoot: { newRoot: "$user.profile" }中某个文档的user字段不存在，或profile是null/[]/""，整个阶段失败 - 即使字段存在但类型不符（比如
profile是字符串而非对象），也会报错 - 无法直接用
$$ROOT“原样透传”，{ $replaceRoot: { newRoot: "$$ROOT" } }虽语法合法，但会重置文档层级，破坏后续$unwind或$lookup的路径匹配
$replaceWith 怎么用才安全？
$replaceWith 支持任意表达式，天然适配真实数据的不确定性：
- 想把整个原始文档包进
data字段？直接写{ $replaceWith: { data: "$$ROOT" } } - 想把
items数组提为根？{ $replaceWith: "$items" }—— 它能自动展开数组，每个元素变成独立文档 - 想 fallback 到默认结构？
{ $replaceWith: { $ifNull: [ "$payload", { status: "missing", code: 404 } ] } } - 配合
$mergeObjects合并字段更自然：{ $replaceWith: { $mergeObjects: [ { _id: "$_id", timestamp: "$$NOW" }, "$detail" ] } }
Go/Node.js 驱动里该选哪个？
驱动层没有额外封装，区别完全取决于你写的聚合阶段。但实际项目中：
- 用
$replaceRoot前必须加$match过滤掉所有可能缺失目标字段的文档，否则线上聚合一跑就崩 -
$replaceWith可以和$ifNull、$cond组合，一行表达式兜底，省去多 stage 搭配 - 如果你只是想“保留全部字段 + 加个 wrapper”，
$addFields+$$ROOT比任何 replace 都更轻量、语义更清晰
真正容易被忽略的是：这两个操作不是“功能相似、选一个就行”，而是 $replaceWith 解决了 $replaceRoot 的设计缺陷——它不假设数据干净，而是让开发者控制容错逻辑。别再用 $replaceRoot 做条件包装，那不是它的设计场景。
