首选 update_one（python）或 updateone（node.js）配合 upsert=true / { upsert: true }，需搭配唯一查询条件和 $set 操作符，并预先建立 unique 索引；否则高并发下仍可能重复插入。
直接结论：用 update_one（Python）或 updateOne（Node.js）配合 upsert=True / { upsert: true }，但必须搭配唯一查询条件 + $set 操作符，且底层必须建好 unique 索引兜底。
为什么 update_one + upsert=True 是首选写法
它把“查是否存在 → 决定插入还是更新”压缩成原子操作，避免应用层竞态：两个请求同时 find 不到，然后都 insert_one 成功，造成重复。而 update_one 的匹配和写入在服务端是原子的。
- 漏写
upsert=True（默认是False）会导致查不到就什么都不做，数据丢失 - 查询条件不能太宽，比如只用
{"name": "Alice"}—— 同名用户多时会误覆盖 - 必须用业务上真正唯一的字段做条件，如
{"email": "a@b.com"}或{"order_id": "ORD-123"}
不加 unique 索引，upsert 就是纸老虎
高并发下，两个请求几乎同时执行 update_one，都判断“没匹配到”，于是都触发插入逻辑——MongoDB 无法靠 upsert 自身阻止这种竞态。唯一索引才是最终防线，它会在第二个插入尝试时抛出 11000 duplicate key 错误。
- 建索引前必须清理已有重复数据，否则
createIndex({ email: 1 }, { unique: true })直接失败 - 字符串末尾空格、大小写差异会导致索引“失效”，需加
collation: { locale: "en", strength: 2 } - 字段允许为
null且业务上要视作占位？改用稀疏索引：{ unique: true, sparse: true } - 建完务必运行
db.collection.getIndexes()，确认状态是"ready"，别信命令没报错就成功了
upsert 默认会清空旧字段，$set 不是可选项
如果你传的是普通对象 {"name": "Alice", "email": "a@b.com"}，upsert 匹配到旧文档后，会用这个对象**完全替换**整个文档，旧的 createdAt、status 字段全丢。
- 永远用
$set：例如{"$set": {"name": "Alice", "updatedAt": new Date()}} - 想新文档才设创建时间？加
$setOnInsert：{"$set": {"updatedAt": new Date()}, "$setOnInsert": {"createdAt": new Date()}} - 分片集合中使用 upsert，
filter必须包含完整分片键，否则报错Cannot upsert with query that does not contain the shard key
Python 和 Node.js 的典型调用差异
Python（pymongo）里 update_one 的第三个参数是布尔值：upsert=True；Node.js（mongoose）里是对象选项：{ upsert: true, new: true }。两者都要求第一个参数 filter 精确、第二个参数 update 带 $set。
- Python 示例：
collection.update_one({"email": user_email}, {"$set": user_data}, upsert=True) - Node.js 示例：
User.findOneAndUpdate({ email: userObj.email }, { $set: userObj }, { upsert: true, new: true }) - 注意 Node.js 中
new: true才返回更新后的文档，否则返回旧文档（或 null）
真正容易被忽略的是：upsert 解决的是“幂等写入”，不是“自动去重”。它依赖你提前定义好哪个字段算“重复”，以及这个字段在数据库里是否真的唯一——后者只能靠 unique 索引保证，任何应用层逻辑都不可信。
