Mongoose $lookup聚合关联集合时返回空数组问题排查

核心根因 #

该问题与聚合语法无关，属于Mongoose特性与Mongo原生匹配规则的认知偏差，也是Mongo Playground可正常运行、本地执行失败的核心原因：Playground中测试数据为手动构造，字段类型、集合名完全匹配，而Mongoose会按默认规则处理Schema类型、集合名映射，极易出现两类关联不匹配的问题：

• 关联字段类型不一致
  Mongoose默认会为未显式指定_id类型的Schema生成ObjectId类型的主键，若Skill集合未手动将_id设为String类型，即使写入时传入字符串值，实际存储的_id也会被转为ObjectId格式；而UserSkill集合中skillID定义为String类型，Mongo的$lookup等值匹配不会做隐式类型转换，字符串格式的ID与ObjectId格式的ID会被判定为不相等，直接导致关联结果为空。

  注意：字符串"650a1b2c3d4e5f6a7b8c9d0e"与ObjectId("650a1b2c3d4e5f6a7b8c9d0e")在Mongo匹配逻辑中属于完全不同的值，无法命中关联。

• $lookup阶段指定的集合名错误
  Mongoose默认会将传入的模型名转为小写复数形式映射到实际集合，例如mongoose.model('Skill', skillSchema)会映射到skills集合；若建模时传入第三个参数手动指定了集合名，或模型名存在拼写偏差，$lookup会读取不存在的集合，自然返回空数组。

修复方案 #

按以下优先级排查修复：

1. 统一关联字段类型（优先推荐，性能最优）
   选择以下任意一种方式统一两边字段类型即可：
   • 调整Schema定义：将UserSkill集合中skillID的类型改为mongoose.Schema.Types.ObjectId，写入数据时直接传入Skill文档的_id值即可，类型会自动对齐，Schema示例：

     const userSkillSchema = new mongoose.Schema({
       userID: { type: String, required: true },
       skillID: { type: mongoose.Schema.Types.ObjectId, ref: 'Skill', required: true }
     })
     

   • 存量数据兼容方案：如果已有大量存量String格式的skillID数据不想修改，可使用管道式$lookup在关联阶段做类型转换，统一为字符串后再匹配，聚合示例：

     UserSkill.aggregate([
       { $match: { userID: '指定查询的用户ID' } },
       {
         $lookup: {
           from: 'skills',
           let: { targetSkillId: '$skillID' },
           pipeline: [
             {
               $match: {
                 $expr: { $eq: [{ $toString: '$_id' }, '$$targetSkillId'] }
               }
             }
           ],
           as: 'skill'
         }
       }
     ])
     

2. 校验集合名映射
   直接连接本地Mongo实例执行show collections命令，确认技能集合的实际名称，与$lookup中from字段的值完全保持一致即可。若建模时手动指定了集合名，例如：

   // 第三个参数指定实际集合名为'skill_list'，则$lookup的from字段必须填'skill_list'
   mongoose.model('Skill', skillSchema, 'skill_list')
   

快速验证方法 #

修复前可单独查询单条Skill文档与单条关联的UserSkill文档，分别打印两个待关联字段的类型与值：

• 打印Skill文档的_id字段值与类型
• 打印UserSkill文档的skillID字段值与类型
  确认两个字段值完全相同、类型一致后，$lookup即可正常返回关联结果。

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