MongoDB $jsonSchema 验证要求更新后完整文档合规，故直接添加 required 字段会使含缺失字段的旧文档在 insertOne/updateOne 时全部失败；安全落地需三步：先放宽为可选或允许 null，再批量补值，最后收紧为 required。
不能直接加 required: true 字段到已有集合——这会导致所有现有文档插入/更新失败。 MongoDB 的 $jsonSchema 验证是写入时全量校验，不是“只校验新增字段”。你加一个必填字段，等于要求每条旧文档都立刻补上该字段，否则 insertOne、updateOne 全部报 Document failed validation。
为什么 updateOne 也会被阻断
很多人误以为“我只是改一个字段，MongoDB 应该只校验那个字段”，但实际规则是：updateOne 后的整个文档必须通过 schema 校验。哪怕你只用 $set 更新一个字段，MongoDB 仍会加载当前文档（含缺失字段）、合并变更、再对完整结果做验证。
- 旧文档没有
phone字段 → 即使你只执行db.users.updateOne({ _id: ... }, { $set: { status: "active" } })，也会因phone缺失而失败 - replaceOne 更危险：它直接替换整个文档，缺失字段必然触发验证失败
- upsert 的插入分支同样受阻，无法兜底
安全添加非空字段的三步落地法
核心思路：先让新字段“可选但存在”，再批量补值，最后收紧为必填。全程不中断业务写入。
-
第一步：放宽 schema，允许字段缺失或为 null
把新字段定义为"bsonType": ["string", "null"]，并移除"required"或设为false。例如：{ "phone": { "bsonType": ["string", "null"], "description": "optional until migration complete" } } -
第二步：后台批量补全字段值
用updateMany分批填充（避免长事务锁表）：db.users.updateMany( { phone: { $exists: false } }, { $set: { phone: "" } }, { multi: true, writeConcern: { w: "majority" } } )注意：补空字符串或默认值比补null更稳妥，尤其当应用层有非空判断逻辑时 -
第三步：升级为 required，且确保无遗漏
确认补全完成（查db.users.countDocuments({ phone: { $exists: false } })返回 0）后，再更新 schema，加入"required": ["phone"]
用 Mongoose 时的额外注意点
Mongoose 的 required: true 是应用层验证，不等同于 MongoDB 原生 $jsonSchema。如果你只在 Schema 里加了 phone: { type: String, required: true }，但没同步更新数据库的 validator，那只是 JS 层报错，绕过 Mongoose 直连 shell 插入仍能成功——这会造成数据不一致。
- 务必双端对齐：Mongoose Schema + 集合级
collMod或createCollection的validator - 不要依赖
default自动填充来“解决”必填问题：default 只在 Mongoose.save() 时生效，对insertOne、bulkWrite 等直连操作无效 - 上线前用真实流量镜像跑一次验证脚本，检查是否有字段类型冲突（比如旧数据存的是数字
13812345678，而新 schema 要求字符串）
最容易被忽略的是验证生效范围：它只卡在写入入口，对历史数据静默无感。这意味着你改完 schema 后，必须主动扫描存量文档是否真满足新规则——靠“没报错”不等于“已合规”。
