本文详解如何使用 mongodb 聚合管道（`$unwind` + `$match` + `$group`）完整保留嵌套数组中**所有满足正则匹配的子文档**，并正确重组为原始结构，避免因误用 `$replaceroot` 或 `$mergeobjects` 导致的单元素数组问题。
在处理如 pictures 这类嵌套数组时，常见误区是：先 $unwind 展开，再 $match 筛选，最后试图通过 $addToSet 或 $push 汇总匹配项——但若后续错误地引入 $replaceRoot 与 $mergeObjects，极易破坏数据聚合逻辑，导致每个 _id 组只保留一个匹配项（实际是 $first 取值覆盖了多匹配场景）。
核心问题在于原管道中这段逻辑：
{"$group": { "_id": "$_id", ... "root": {"$first": "$$ROOT"} }},
{"$replaceRoot": { "newRoot": { "$mergeObjects": ["$root", {"pictures": "$pictures"}] }}}它本质是「先按 _id 分组 → 取任意一条原始文档（$first: "$$ROOT"）→ 再强行合并 pictures 数组」。但由于 $first: "$$ROOT" 是非确定性取值（且未保证该文档的 pictures 字段与当前匹配项关联），最终 $mergeObjects 实际只注入了 $addToSet 聚合后的 pictures，而 $$ROOT 中的原始 pictures 已被 $unwind 破坏，造成语义混淆和结果截断。
✅ 正确解法是彻底剥离对原始根文档的依赖，仅聚合所需字段：
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
- 使用 {"_id": {"$toString": "$_id"}} 显式转换 _id 类型（适配 JSON 序列化）；
- 用 $first 安全提取 url 和 source（它们在同 _id 文档中恒定）；
- 用 $push（非 $addToSet）收集所有匹配的 pictures 子文档（$addToSet 会去重，但此处需保留重复 name 的不同 version）；
优化后的聚合管道如下：
pipeline = [
{"$unwind": "$pictures"},
{"$match": {"pictures.name": {"$regex": pattern}}},
{"$group": {
"_id": {"$toString": "$_id"},
"url": {"$first": "$url"},
"source": {"$first": "$source"},
"pictures": {"$push": "$pictures"} # ✅ 关键：用 $push 保留全部匹配项
}},
{"$project": {
"_id": 1,
"url": 1,
"source": 1,
"pictures": 1
}}
]⚠️ 注意事项：
- 勿混用 $addToSet 与 $push：$addToSet 适用于去重场景（如 name 唯一），但本例中同一 name 可能有多个 version（如 "pines" 出现在不同文档中），必须用 $push；
- 避免 $replaceRoot + $$ROOT：$$ROOT 在 $unwind 后已不包含原始嵌套结构，强行合并反而引入不确定性；
- $toString 提前转换 _id：防止 ObjectId 在 JSON 序列化时报错，比后期 {"_id": {"$toString": "$_id"}} 更清晰；
- 若需支持大小写敏感/模糊匹配，可扩展正则标志（如 re.DOTALL）或改用 $text 索引（需提前建全文索引）。
最终返回结果将严格符合预期：每个匹配的顶层文档（_id）下，pictures 数组完整包含该文档内所有 name 匹配查询字符串的子对象，结构清晰、语义准确，可直接用于前端渲染或下游处理。
