$适用于一层嵌套数组更新，简单安全；多层嵌套必须用arrayfilters配合$[identifier]；下标硬编码仅限下标稳定场景；复杂嵌套应重构为引用模型。
只有一层嵌套时，用 $ 最简单也最安全
如果你要更新的数组字段是顶层或一级嵌套（比如 comments、tags、entries），且目标元素能通过简单条件唯一匹配第一个，$ 就是首选。它不依赖路径声明、不需额外配置、驱动兼容性好，连 MongoDB Community 6.0+ 都完全支持。
常见错误现象：写对了查询条件但 $set 没生效，往往是因为查询里漏掉了数组字段的点路径 —— 比如想更新 entries.x === "hello" 的 y 值，查询必须带 "entries.x"，不能只写 { x: "hello" }。
-
updateOne({ "entries.x": { $type: "string" } }, { $inc: { "entries.$.y": 33 } })是正确写法 - 不能在
upsert: true场景下用$，否则驱动会把$当成字段名插入，生成类似{"$": ...}的无效字段 -
$只匹配第一个符合条件的元素，无法控制“第几个”或“所有”，这点和业务预期不符时就得换方案
两层及以上嵌套必须用 arrayFilters + $[identifier]
一旦结构变成 user.roles.permissions 或 order.items.variants 这种多级数组，$ 完全失效，MongoDB 会直接报错或静默忽略更新。这时唯一可靠的方式是组合 arrayFilters 和带标识符的 $[r]、$[p] 等占位符。
最容易踩的坑是“配对缺失”：写了 arrayFilters 却没在更新路径里用对应 $[x]，MongoDB 不报错，但 $set 根本不执行 —— 日志里也看不到失败提示，非常难排查。
- 更新路径中每个
$[x]必须有且仅有一个arrayFilters条件与之严格对应，键名大小写敏感（{"r.name": "admin"}≠{"R.name": "admin"}） - 层级顺序不能颠倒：文档是
a.b.c，就必须写a.$[a].b.$[b].c，不能跳过中间层或交换顺序 - 无法用通配符跳级，比如不存在
a.*.c这种语法；哪怕某层数组恒为单元素，也得显式声明$[x]并配过滤器
下标硬编码只适合客户端已知位置的场景
如果业务逻辑已经明确知道要改的是第几个元素（比如前端传了 comments[2].replies[0].votes），直接用数字下标是最直白的方案："comments.2.replies.0.votes"。它绕过了所有运算符解析，性能最好，也最容易调试。
但这个方式极度脆弱：一旦数组发生增删（比如有人删了第 1 条评论），原本的下标就错位了，后续更新会写到错误元素上，甚至因越界导致整个操作失败。
- 仅推荐用于临时脚本、管理后台手动修正，或客户端能 100% 保证下标稳定的极少数场景（如固定配置项数组）
- 永远不要在用户生成内容的主业务流中依赖下标，尤其是涉及并发写入时，竞态条件会让下标瞬间失效
- 配合
$elemMatch先查出目标元素位置再拼下标，看似稳妥，实则引入额外 round-trip，且仍无法规避并发修改风险
复杂嵌套优先考虑重构数据模型
当你发现自己反复写三层以上 arrayFilters，或者为了更新一个字段要声明四五个 $[x] 占位符，这通常是模型设计过载的信号。MongoDB 对深度嵌套数组的更新支持有限，且每次操作都需全路径匹配，性能随层数指数下降。
真正省事的做法不是写更复杂的查询，而是把频繁更新的子结构拆成独立集合，用 ObjectId 引用关联。比如把 user.teams.members.tasks 拆成 teams、members、tasks 三个集合，用 teamId、memberId 字段连接。
- 引用模型让单次更新聚焦在一个小文档上，避免跨多层数组扫描
- 天然支持事务（4.0+），能保证关联更新的原子性，而深层嵌套数组更新无法回滚中间状态
- 即使要查整条链路，用
$lookup聚合也比嵌套数组查询更可控，尤其当某层数据量大或需分页时
嵌套不是错，但当定位更新开始需要查文档结构、反复验证 arrayFilters、甚至写辅助脚本来生成更新语句时，说明该停下来重审模型了 —— MongoDB 的优势不在深度嵌套，而在灵活适配访问模式。
