updateOne()（更新单条）
最后更新：2026-10-09
updateOne()（更新单条）
updateOne() 更新集合中**匹配条件的第一条**文档。若有多条匹配，只更新第一条（按自然顺序）。更新操作需用更新操作符（$set/$inc/$push 等）指定修改。返回结果含 matchedCount、modifiedCount、upsertedId 等字段。
| 分类 | 写入 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
db.<集合>.updateOne(<过滤条件>, <更新操作>, { upsert: <bool> })⚙️ 参数
| 过滤条件 | 匹配文档的条件对象，支持查询操作符。 |
|---|---|
| 更新操作 | 更新操作符组成的对象，如{$set: {age: 22}}。 |
| upsert | 可选。无匹配时是否插入一条新文档，默认false。 |
返回值：UpdateResult对象：{ acknowledged, matchedCount, modifiedCount, upsertedId }。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// updateOne：把 Alice 的年龄改为 22
db.users.updateOne(
{ name: "Alice" },
{ $set: { age: 22 } }
)运行结果：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 注意事项
- 只更新第一条匹配文档；用 updateMany() 更新全部
- 更新文档必须使用更新操作符，不能直接覆盖（除非用 replaceOne）
- upsert: true 时无匹配则插入新文档
- 更新操作符不能混用冲突字段（如同一字段同时 $set 和 $inc）
🏷️ 相关标签
💡 相关案例
📚 相关教程
❓ 常见问题
QupdateOne 和 findOneAndUpdate 什么区别？
AupdateOne 只返回统计结果（matched/modifiedCount），findOneAndUpdate 返回更新前（或后）的文档本身，适合需要读取旧值/新值的场景。
QupdateOne 匹配多条时怎么处理？
A只更新匹配到的第一条文档。若需要更新所有匹配文档，用 updateMany；如果担心更新顺序，可配合 sort 选项指定「第一条」的顺序。
QupdateOne 的过滤条件可以结合 $set 和 $inc 吗？
A可以。更新文档里可同时含多个更新操作符，如 { $set: { status: 'active' }, $inc: { visits: 1 } }，它们按序原子生效。
