replaceOne 必须显式传入且严格匹配 _id，否则报错或丢失字段；推荐用 structuredClone 保留类型，避免 JSON.stringify/parse；它用于彻底重置文档，而 updateOne+$set 仅更新部分字段。
replaceOne 不能跳过 _id，必须显式传入且值严格一致，否则直接报错或静默丢失字段。
replaceOne 要求 _id 必须出现在替换文档里
很多人误以为 replaceOne 会自动保留原 _id，实际它完全不管“来源”，只认你传进去的 replacement 对象里有没有 _id 字段、值是否匹配。
- 不带
_id：操作成功但新文档变成无_id的普通对象（MongoDB 允许，但通常不是你想要的） -
_id值不匹配：抛出WriteError: The _id field cannot be changed -
_id类型错误（比如字符串代替ObjectId）：等价于“值不匹配”，同样报错
构造替换文档时别用 JSON.stringify + JSON.parse
原始文档里的 _id: ObjectId("...") 经过 JSON.stringify 后会变成字符串，再 JSON.parse 就彻底丢失类型，导致后续 replaceOne 拒绝写入。
- ✅ 推荐：用
structuredClone(original)（Node ≥17）——保留ObjectId、Date等原生类型 - ✅ 备选：手动重建
_id，例如{ ...updates, _id: new ObjectId(original._id) } - ❌ 避免：
JSON.parse(JSON.stringify(original))，尤其在涉及嵌套或自定义类型时
为什么不用 updateOne + $set？语义不同
replaceOne 的目标是“清空旧字段 + 写入新字段”，而 updateOne + $set 是“只改指定字段，其余不动”。如果你要删掉几十个旧字段，靠 $unset 显式列出所有字段极易遗漏。
- 适用
replaceOne：需要彻底重置文档结构（如导入清洗后的新数据、迁移 schema） - 适用
updateOne：只更新部分字段，且希望保留未提及的旧字段（如仅更新用户头像，不碰昵称、邮箱） - 注意：两者性能差异明显 ——
replaceOne是读+写两轮；updateOne是原子单次操作
容易被忽略的只读字段也要一并保留
除了 _id，有些场景下还有隐式只读字段，比如 Mongoose 的 __v（版本键）、某些 ORM 注入的审计字段（createdAt、updatedAt）。如果这些字段不在你的 replacement 中，replaceOne 会把它们连同其他旧字段一起删掉。
- 检查原始文档结构：
console.log(original)，确认是否有非业务字段 - 构造时显式继承：
{ ...original, ...updates, _id: original._id }，而不是手写新对象字面量 - 若需剔除某些业务字段（如临时缓存字段），应在解构后明确过滤，而非依赖“没写就等于删”
