直接用 $set 更新数组某位置失败，主因是路径中某级字段不存在或类型不匹配（如 items 为 null 或空数组）；应优先用 $[elem] 配合 arrayFilters 按条件更新，避免硬编码索引。
为什么直接用 $set 更新数组某个位置会失败
当你写 collection.update_one({"_id": 1}, {"$set": {"items.0.name": "new"}}) 却发现没生效，大概率是因为 items 字段根本不存在，或者 items 不是数组（比如是 null 或对象）。MongoDB 的点号路径更新要求路径上每一级都必须存在且类型匹配。如果 items 是 null，items.0 就不合法；如果 items 是空数组 []，索引 0 也越界。
- 先确认数组存在且非空：
find_one({"_id": 1, "items.0": {"$exists": True}}) - 若不确定长度，优先用
$[]或$[elem]配合arrayFilters，而不是硬写索引 - 避免在生产代码里拼接字符串索引（如
f"items.{i}.name"），容易注入或越界
用 $[elem] 占位符精准定位数组内满足条件的元素
这是最安全、最常用的“更新符合条件的数组项”方式。它不依赖索引位置，而是靠数组元素自身的字段值匹配，天然规避越界和结构缺失问题。
collection.update_one(
{"_id": 1},
{"$set": {"items.$[elem].status": "done"}},
array_filters=[{"elem._id": {"$eq": ObjectId("...")}}]
)
-
$[elem]是占位符，必须配合array_filters参数使用，否则报错InvalidPathExpression -
array_filters中的elem名称要和$[...]里的一致，大小写敏感 - 如果数组里有多个元素匹配
array_filters，$[elem]会更新所有匹配项（不是只更新第一个） - 不支持嵌套多层占位符，例如
items.$[a].subitems.$[b].val是非法的
批量更新多个数组元素时，$[] 和 $[elem] 的区别
$[] 是“无条件更新整个数组所有元素”，而 $[elem] 是“按条件筛选后更新”。选错会导致误改数据。
- 想把所有
items的processed设为True？用"items.$[].processed" - 只想更新
type == "urgent"的那些？必须用"items.$[elem].processed"+array_filters=[{"elem.type": "urgent"}] -
$[]不需要array_filters，但无法做条件判断；用了array_filters却写$[]，过滤器会被忽略 - 如果数组为空，
$[]什么也不做，不会报错；$[elem]在无匹配时也静默跳过
更新嵌套数组时的常见陷阱
当数组元素本身还包含数组（例如 items: [{tags: ["a", "b"]}]），试图用 items.0.tags.1 直接更新第二个 tag，极可能失败——因为 MongoDB 不支持多级动态索引。
立即学习“Python免费学习笔记（深入）”；
- 不能写
"items.0.tags.1"去改某个 tag，除非你 100% 确定两级索引都存在 - 要更新
tags数组中某个值，得用双重arrayFilters（4.0+）："items.$[i].tags.$[t]"，并传入两个过滤器 - 更稳妥的做法：读出文档 → 在 Python 里用列表推导式修改 →
replace_one整体写回（适合小数组或低频操作） - 注意
arrayFilters中的变量名不能重复，也不能和顶层字段名冲突（如不能用items作占位符名）
find_one 检查目标文档结构，再决定用 $[elem] 还是 $[]；任何涉及索引数字的写法，都要前置校验长度。占位符看着绕，但它把“意图”和“结构假设”分开了——这才是可维护的关键。 
