MongoDB聚合报错：管道阶段规范对象必须恰好包含一个字段

抛出MongoServerError: A pipeline stage specification object must contain exactly one field.错误的核心原因是MongoDB聚合管道的语法规则要求：管道数组中的每一个元素必须是仅包含单个顶级聚合操作符的对象。
你当前的代码把$unwind、$match两个独立的聚合阶段写在了同一个对象里，单个对象同时存在两个顶级聚合字段，完全不符合管道语法要求。
你在MongoDB Compass中测试正常，是因为Compass的GUI会自动把每个配置的阶段拆分为独立的单字段对象存入管道数组，你导出代码时没有注意到两个阶段是分开的两个数组元素，误将其合并到了同一个对象中。这个问题和你传的includedInBom参数值没有关系，哪怕硬编码productId，结构错误的问题依然存在。

你当前实现返回的是单个包含两个操作符的对象，属于非法结构：

// 非法结构：单个阶段对象包含两个顶级聚合操作符
const includedInBomStage = {
  $unwind: {
    path: '$finale.bomItems',
  },
  $match: {
    'finale.bomItems.productId': includedInBom,
  },
}

将两个聚合阶段拆分为独立的单字段对象，以数组形式返回即可，使用时直接把返回的数组合并到你的聚合管道数组中：

const formatIncludedInBomStage = ({ includedInBom }) => {
  // 每个对象仅包含一个聚合操作符，作为独立的管道阶段
  return [
    {
      $unwind: {
        path: '$finale.bomItems',
      },
    },
    {
      $match: {
        'finale.bomItems.productId': includedInBom,
      },
    }
  ]
}

内容的提问来源于stack exchange，提问作者Eric Pezzulo