$avg只能在$group（或$setWindowFields）中使用，因其是累加器操作符，不能用于$project或$match；错误写法如{$project:{avg:{$avg:"$f"}}}会报“unknown operator”；正确须配合_id（如{_id:null, avg:{$avg:"$f"}}）。
为什么 $avg 在 group 阶段外无效？
$avg 是聚合管道中的累加器操作符，只能用在 $group 阶段（或 $setWindowFields 中），不能直接写在 $project 或 $match 里。常见错误是试图这样写：{$project: {avgScore: {$avg: "$score"}}}——这会报错 unknown operator: $avg。
它必须配合 _id 字段一起出现在 $group 中，哪怕你只是想算全集合平均值，也要写 _id: null。
- 正确写法：
{$group: {_id: null, avgScore: {$avg: "$score"}}} - 按字段分组：
{$group: {_id: "$category", avgPrice: {$avg: "$price"}}} - 嵌套字段支持：
{$avg: "$ratings.value"}，但要求ratings.value是数值类型，否则被忽略（不报错）
空值、缺失字段和非数字值怎么处理？
$avg 会自动跳过 null、缺失字段、NaN 和非数字类型（如字符串 "12.5"），不会报错，但结果可能比预期小——因为分母只计有效数值个数。
比如文档中有 10 条记录，其中 3 条 score 是 "95"（字符串）、2 条是 null、1 条是 {}（对象），实际参与计算的只有剩下 4 个数字，平均值基于这 4 个算。
- 想强制转换字符串数字？得先用
$toDouble或$toInt清洗：{$avg: {$toDouble: "$score"}} - 想排除
0值？$avg不支持条件过滤，需前置$filter或用$cond构造新数组 - 检查是否有非数字数据：加一个
$match: {score: {$type: "number"}}放在$group前
和 $sum / $count 搭配使用时要注意什么？
单独用 $avg 看不出问题，但一旦需要同时输出平均值、总数、总和，容易误以为 $sum 和 $avg 统计的是同一组数据——其实它们都基于 $group 当前上下文，是同步的，这点没问题；真正容易错的是字段路径不一致。
例如：$avg: "$rating" 和 $sum: "$reviewCount" 如果来自不同嵌套层级，或者一个拼写错（比如 "ratting"），就会导致部分字段为 null，而 $avg 仍能算出结果（只是分母变小）。
- 建议统一用
$ifNull设默认值：{$avg: {$ifNull: ["$score", 0]}}，但注意：填 0 会拉低平均值，慎用 - 验证数据分布：在
$group前加$addFields+$type查看字段真实类型 - 性能提示：如果集合很大且只关心平均值，
$group后尽早$limit: 1，避免后续阶段处理冗余数据
在 MongoDB Shell 和驱动中调用有啥区别？
语法本身没区别，但 Node.js 的 mongodb 驱动（v5+）默认返回游标，不是直接结果；Python 的 pymongo 同理。很多人写了正确的聚合管道，却忘了 .toArray() 或 list()。
Shell 里直接执行就打印结果；代码里不消费游标，等于什么都没拿到——控制台也没报错，容易误判为“没数据”或“逻辑不对”。
- Node.js 示例：
collection.aggregate([{$group: {_id: null, avg: {$avg: "$x"}}}]).toArray() - Python 示例：
list(collection.aggregate([{"$group": {"_id": None, "avg": {"$avg": "$x"}}}])) - 别漏掉异步等待（Node.js）或循环取值（Python），否则得到的是游标对象，不是数字
聚合里 $avg 本身很简单，难的是确认输入数据干净、路径准确、调用方式完整——这三个地方任一出错，结果都可能静默偏差。
