findOneAndReplace()（替换并返回文档）
最后更新：2026-10-09
findOneAndReplace()（替换并返回文档）
findOneAndReplace()用一份新文档整体替换第一条匹配过滤条件的文档，并返回替换前或替换后的文档，例如`db.users.findOneAndReplace({ name: 'Bob' }, { name: 'Bob', age: 26 }, { returnDocument: 'after' })`。它与replaceOne()的区别在于能读回文档内容，适合需要拿到替换结果的场景。除_id外的所有字段都会被新文档覆盖。
| 分类 | 写入 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
db.<集合>.findOneAndReplace(<过滤条件>, <新文档>, { returnDocument: 'after', upsert: <bool> })⚙️ 参数
| 过滤条件 | 匹配要替换文档的条件对象。 |
|---|---|
| 新文档 | 完整的新文档，覆盖除_id外的所有字段。 |
| returnDocument | 可选。'before'返回替换前文档，'after'返回替换后文档，默认'before'。 |
返回值：替换前（或替换后）的文档；无匹配且未开启upsert时返回null。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// findOneAndReplace：整体替换Bob的文档并返回新文档
const doc = db.users.findOneAndReplace(
{ name: 'Bob' }, { name: 'Bob', age: 26, vip: true },
{ returnDocument: 'after' }
)
doc运行结果：
{
_id: ObjectId('64c8a1b20000000000000002'),
name: 'Bob',
age: 26,
vip: true
}📌 注意事项
- 新文档必须保留原_id，否则报错
- 返回的_id始终是原文档的_id（即使upsert插入新文档）
- 替换是整体覆盖，先确认新文档包含所需全部字段
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
QfindOneAndReplace和replaceOne有什么区别？
AreplaceOne()只返回统计数字；findOneAndReplace()返回替换前或替换后的文档本身。
QfindOneAndReplace能改_id吗？
A不能，新文档必须保留原_id，否则操作会报错。
Qupsert开启时findOneAndReplace返回什么？
A无匹配时会插入新文档并返回它；此时返回的_id就是新生成的_id。
