replaceOne 是什么
replaceOne 是 MongoDB 的整文档替换写操作：按过滤条件找到第一条匹配文档，用给定的新文档整体覆盖它的内容。它和 updateOne 的区别在于 updateOne 用 $set 一类更新操作符做局部修改并保留其它字段，replaceOne 的第二个参数必须是纯文档，出现 $ 开头的键会直接报错。替换后原文档里没在新文档出现的字段全部消失，所以它适合整条记录被完整重新提交的场景，不适合只改一个字段。
基本信息
| 所属系统 | MongoDB 3.2 起（mongosh 与各语言驱动均支持） |
|---|---|
| 语法 | db.collection.replaceOne(filter, replacement, options) |
| 返回字段 | matchedCount / modifiedCount / upsertedId |
| 常用选项 | upsert、collation、hint、writeConcern |
| 权限要求 | 集合上的 update 权限 |
典型使用场景
- 表单整体回写：页面上编辑的是完整对象，业务直接用提交内容覆盖旧文档
- 结构性重建：字段命名或嵌套层级调整，用操作符难以表达时整体替换更直接
- 外部快照同步：上游给的是一条完整记录，整体落库最省事
- 清理历史脏字段：把早期版本遗留的多余字段一次性清掉
- 数据修复：文档被误写后按备份内容整条还原
基本用法
基本用法
db.users.replaceOne(
{ email: "a@example.com" }, // 过滤条件，只替换匹配到的第一条
{ email: "a@example.com", name: "Alice", level: 2 }, // 新文档，不能出现 $ 开头的键
{ upsert: false } // 未匹配时不插入新文档
)
// 返回值必须检查，未匹配时不会报错
const r = db.users.replaceOne({ _id: 1 }, { _id: 1, name: "Bob" })
print(r.matchedCount, r.modifiedCount) // 0 表示没匹配到目标文档参数与返回值
| 项 | 含义 | 注意 |
|---|---|---|
| filter | 匹配条件 | 只替换第一条，条件要能唯一定位 |
| replacement | 替换文档 | 不能含 $ 操作符；_id 可省略，省略则沿用原值 |
| upsert | 未匹配时是否插入 | 为 true 时按条件和替换文档生成新文档 |
| matchedCount | 命中条数 | 0 表示未匹配，脚本必须判断 |
| modifiedCount | 实际改动条数 | 新旧内容完全相同时可能为 0 |
替换文档里可以不写 _id，此时沿用原文档的 _id；若写了与原值不同的 _id，服务端会因为 _id 不可变更而报错。
replaceOne 会丢弃未列出的全部字段，属于高危写操作。只想改部分字段时请继续使用 updateOne 配合 $set。