$rename 能安全重命名字段，但必须避开嵌套数组、原子性边界和索引失效这三类坑：它本质是单文档内原子性地复制值再删除旧字段；不支持数组内字段（如 comments.0.author）；新字段名存在时直接覆盖；原字段索引立即失效，需提前创建新索引并事后删除旧索引。
直接说结论：$rename 能安全重命名字段，但必须避开嵌套数组、原子性边界和索引失效这三类坑。
为什么 $rename 看似简单却容易出错
很多人以为 $rename 就是“改个名字”，实际它本质是字段值的原子移动：MongoDB 把旧字段的值完整复制到新字段，再删除旧字段。这个过程在单文档内是原子的，但跨文档不保证顺序，更不触发任何钩子或验证逻辑。
- 如果字段在
array内（比如comments.0.author），$rename会失败并报错Cannot rename field inside array - 如果新字段名已存在，
$rename会直接覆盖原值，且不警告 - 重命名后，原字段上的索引（如
{ "oldName": 1 }）立即失效，查询性能可能骤降
正确使用 $rename 的实操步骤
不是一条命令完事，得按节奏分步走，尤其在生产环境。
- 先确认目标字段不在数组中：
db.collection.findOne({ "fieldName.0": { $exists: true } })—— 若返回结果，说明该字段可能位于数组内，不能直接$rename - 用
updateMany+$rename批量操作，但加{ multi: true }已废弃，必须显式写updateMany - 重命名前建好新字段索引：
db.collection.createIndex({ "newFieldName": 1 })，等索引buildPhase变为completed再执行$rename - 执行后立刻检查：
db.collection.find({ newFieldName: { $exists: true } }).count()和db.collection.find({ oldFieldName: { $exists: true } }).count()，确认迁移比例
嵌套对象字段重命名的替代方案
当要重命名的是 user.profile.name 这类路径时，$rename 会报错。此时只能退回到聚合管道 + replaceOne 循环。
- 用
find拉出一批文档（建议每次 ≤ 1000 条），在应用层提取user.profile.name值，赋给user.profile.fullName - 用
replaceOne替换整篇文档（注意保留_id和其他未改动字段） - 或者用聚合管道配合
$set和$unset：db.collection.updateMany( {}, [ { $set: { "user.profile.fullName": "$user.profile.name" } }, { $unset: "user.profile.name" } ] )—— 注意：这种写法在 MongoDB 4.2+ 才支持聚合更新
迁移完成后必须做的收尾动作
很多人停在 “字段名改了” 就以为结束了，其实最关键的收尾常被跳过。
- 删掉旧字段索引：
db.collection.dropIndex("oldFieldName_1")，否则它持续消耗写入性能 - 检查应用代码里所有
.find({ oldFieldName: ... })或.sort({ oldFieldName: 1 })，漏改一处就查不到数据 - 如果用了 Mongoose，模型 Schema 里的
oldFieldName字段定义必须同步删掉或设为select: false，否则toObject()仍会尝试序列化已不存在的字段
最麻烦的不是 rename 本身，而是字段名变更在代码、索引、监控、日志解析规则里的多点散落 —— 改完数据库只是第一步。
