Mongoose修改Schema属性后如何同步更新集合中已有旧文档

Mongoose的Schema本质是应用层的数据校验规则，不会主动修改MongoDB中已经存在的文档，所有存量数据的结构同步都需要显式操作，根据项目所处阶段和数据重要程度选对应方案即可。

项目初期（无需要永久保留的生产数据阶段） #

这个阶段不用做复杂的迁移逻辑，怎么快怎么来：

• 不需要保留旧测试数据的话，直接删除对应集合即可。下次服务启动时，Mongoose会按照新的Schema规则生成新集合，完全没有历史数据包袱。
  可以直接在MongoDB shell/可视化客户端执行db.你的集合名.drop()，也可以写个临时启动脚本调用Model.collection.drop()，执行一次后删掉脚本就行。
• 需要保留已有测试数据的话，写一次性的批量更新脚本，在服务启动前执行一次，跑完就删掉脚本避免重复触发，常见变更场景的写法参考：
  • 新增带默认值的字段：Mongoose的default配置只会对新创建/新执行save操作的文档生效，存量文档不会自动补字段，需要手动批量赋值

  // 示例：给User集合新增isVip字段，默认值为false
  await User.updateMany(
    { isVip: { $exists: false } },
    { $set: { isVip: false } }
  )
  

  • 删除废弃字段：用$unset操作符批量清除所有文档中的冗余字段

  // 示例：移除已经废弃的oldAddress字段
  await User.updateMany(
    { oldAddress: { $exists: true } },
    { $unset: { oldAddress: "" } }
  )
  

  • 字段重命名/类型修改：用$rename或者带聚合管道的updateMany做批量转换

  // 示例1：将userName字段重命名为nickName
  await User.updateMany(
    {},
    { $rename: { userName: "nickName" } }
  )
  
  // 示例2：将字符串格式的age字段转为数字格式
  await User.updateMany(
    { age: { $type: "string" } },
    [{ $set: { age: { $toInt: "$age" } } }]
  )
  

• 如果集合数据量特别小（仅几百上千条测试数据），直接用MongoDB可视化客户端（比如Compass）手动批量修改即可，不用写脚本。

有不可丢失的存量数据阶段（含后续上线阶段） #

不要依赖临时脚本或者第三方自动同步工具，最稳妥的方案是做版本化迁移：

• 在Schema中新增schemaVersion字段，类型为数字，默认值设为当前最新的结构版本号（初始可以设为1）
• 每次调整Schema结构时，将版本号加1，同时写对应版本的迁移逻辑：把低于当前版本的文档，逐批执行结构转换，转换完成后将文档的schemaVersion更新为最新版本号
• 服务启动时先检查存量文档的版本，自动执行未完成的迁移，这种方式不会重复执行迁移逻辑，也不会遗漏数据，后续上线生产环境也可以直接复用。

注意避坑：不要依赖Mongoose查询时自动注入的默认值“假装”字段存在——这种逻辑只在Mongoose查询返回的JS对象层面生效，MongoDB实际存储的文档里并没有对应字段，后续做聚合查询、建索引、原生MongoDB操作时会直接出现字段缺失的问题，必须把字段实际写入存量文档才算同步完成。

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