replaceOne()（整体替换文档）
最后更新：2026-10-09
replaceOne()（整体替换文档）
replaceOne()用一份全新的文档整体替换集合中第一条匹配过滤条件的文档。与updateOne()使用更新操作符不同，replaceOne()的第二个参数就是新文档本身——替换后旧文档的所有字段（除_id外）都会被新文档覆盖。返回结果含matchedCount和modifiedCount。它常用于需要彻底改写文档结构的场景。
| 分类 | 写入 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
db.<集合>.replaceOne(<过滤条件>, <新文档>, { upsert: <bool> })⚙️ 参数
| 过滤条件 | 匹配要替换文档的条件对象。 |
|---|---|
| 新文档 | 完整的新文档，会覆盖除_id外的全部字段。 |
| upsert | 可选。无匹配时插入新文档，默认false。 |
返回值：UpdateResult对象：{ acknowledged, matchedCount, modifiedCount, upsertedId }。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// replaceOne：用新文档整体替换Bob的记录
db.users.replaceOne(
{ name: 'Bob' },
{ name: 'Bob', age: 26, city: 'Shanghai', vip: true }
)运行结果：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 注意事项
- 替换文档必须保留_id（或省略_id让原值保留），否则报错
- 新文档不能含更新操作符，如{$set: ...}会直接当普通字段写入
- 只替换第一条匹配文档，批量替换需逐个或循环处理
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
QreplaceOne和updateOne有什么区别？
AupdateOne()用操作符增量修改字段；replaceOne()用全新文档整体替换，除_id外所有字段都会被覆盖。
QreplaceOne能修改_id吗？
A不能。_id是文档的不可变标识，replaceOne的新文档必须保留原_id，否则报错。
QreplaceOne第二个参数能写更新操作符吗？
A不能。replaceOne的第二个参数就是新文档本身，{$set: ...}这类操作符会被当作普通字段原样写入。
