用 schemaVersion 字段做显式版本标记最稳妥：必须作为文档自身字段（如 NumberInt(1)），禁用注释、配置等外部方式；建议用数字便于查询；迁移需原子更新；读取须按版本降级兼容；索引应复合 schemaVersion 与高频字段。
用 schemaVersion 字段做显式版本标记最稳妥
MongoDB 本身不提供 Schema 版本管理，靠字段命名或结构变化容易漏判。加一个明确的 schemaVersion 字段（如 NumberInt(1) 或 "v2.1"）是唯一能可靠区分文档“属于哪个 Schema 阶段”的方式。
常见错误是把版本信息藏在注释、集合名后缀或应用配置里——一旦文档跨服务流转或被直接写入，这些信息就断了。必须让版本成为文档自身的一部分。
-
schemaVersion建议用数字（如1、2）而非字符串，方便范围查询和排序 - 首次上线时所有新文档都应写入默认值，老文档迁移需批量更新，不能跳过
- 避免用
_version这类易与 MongoDB 内部字段混淆的名字
迁移脚本必须带 schemaVersion 检查和原子更新
升级字段结构（比如把 address 拆成 address.street 和 address.city）时，只靠应用层判断 address 类型是否为字符串会出错：有些文档可能已部分更新，有些字段缺失，有些甚至被手动改过。
真正安全的做法是先查 schemaVersion，再按版本分支处理，最后统一升版：
db.users.updateMany(
{ schemaVersion: { $lt: 2 } },
[
{ $set: {
"address.street": { $cond: { if: { $eq: [{ $type: "$address" }, "string"] }, then: "$address", else: null } },
"address.city": { $literal: "unknown" }
}
},
{ $set: { schemaVersion: 2 } }
]
)
- 千万别用两个独立的
updateMany（先改结构，再升版），中间失败会导致数据不一致 - 聚合管道更新（
updateMany第二参数为数组）支持条件计算，比客户端遍历快且原子 - 对大集合，加
{ multi: true }或用分批limit+skip，避免长时间锁表
应用读取时必须校验 schemaVersion 并降级兼容
新版代码如果假定所有文档都有 address.city，而线上混着 v1 和 v2 文档，就会触发 Cannot read property 'city' of undefined 这类错误。
读取逻辑不能只做“有就用，没有就报错”，得按版本兜底：
// Node.js 示例
function parseUser(doc) {
if (doc.schemaVersion >= 2) {
return { city: doc.address?.city || "unknown" };
} else {
return { city: doc.address === "Beijing" ? "Beijing" : "unknown" };
}
}
- 不要在模型层（如 Mongoose schema）硬编码字段要求，那会让旧文档无法加载
- 如果 v1 到 v2 的语义变化大（比如
status从字符串变成对象），降级逻辑要包含业务含义转换，不只是字段映射 - 日志里记录低版本文档的 ID 和数量，便于发现未完成迁移的脏数据
索引和查询性能受 schemaVersion 影响很实际
加了 schemaVersion 后，如果所有查询都带上 { schemaVersion: { $gte: 2 } }，旧版本文档就被自然过滤掉——但代价是索引膨胀和查询计划变复杂。
更现实的做法是：高频查询走复合索引，冷数据归档另存，而不是靠字段过滤扛流量：
- 给常用查询字段 +
schemaVersion建复合索引，例如{ status: 1, schemaVersion: 1 } - 对已确认无业务访问的 v1 文档，导出后从主集合删除，别长期留着“僵尸版本”拖慢全表扫描
- 如果不同版本字段差异极大（比如 v3 新增全文搜索字段），考虑用分集合策略（
users_v3），但得同步维护路由逻辑
版本字段看着小，但它会出现在每条文档、每个索引、每次序列化里。真正麻烦的不是加字段，而是当某天发现 30% 的文档还卡在 v1，而新功能又强依赖 v3 结构时——那时候补迁移脚本，比一开始设计好版本跃迁路径难十倍。
