Firebase Firestore set操作中overwrite与merge的区别是什么

架构老林

2026-10-26

Firebase Firestore 中 Overwrite 与 Merge 的核心差异

很多人刚接触set操作时，会因为测试场景的巧合把两个概念搞混，实际上二者的执行逻辑、对原有文档的影响完全不同，直接拿实际执行效果举例最清楚：

两种操作的实际执行行为

我们先假设数据库里存在一个ID为user_001的已有文档，原有内容如下：

// 文档原有内容
{
  username: "test_user",
  age: 25,
  city: "上海",
  profile: {
    bio: "喜欢写代码",
    gender: "男"
  }
}

这是set操作的默认逻辑，规则非常直接：
本次请求传入什么内容，整个文档就会被彻底替换成该内容。原有文档里所有没有出现在本次请求参数中的字段，无论嵌套层级多深，都会被直接删除，没有任何保留。

还是以上述原有文档为基础，执行不带merge的set操作，传入参数仅为{age: 26}，执行完成后文档的实际内容为：

// overwrite执行后的文档结果
{
  age: 26
}

所有没有在本次请求中传入的字段（username、city、profile）全部被清空删除，没有任何痕迹留存。

只有在set调用时显式传入{merge: true}（或指定需要merge的字段路径），才会触发该逻辑：
本次请求传入哪些字段，就仅把这些字段的旧值替换为新值。原有文档里所有没有出现在本次请求参数中的字段，会原封不动保留，不会被删除。

同样以上述原有文档为基础，还是传入{age: 26}，但这次带上{merge: true}参数，执行完成后文档的实际内容为：

// merge执行后的文档结果
{
  username: "test_user",
  age: 26,
  city: "上海",
  profile: {
    bio: "喜欢写代码",
    gender: "男"
  }
}

仅age字段被更新为新值，其他原有字段完全保留，没有任何改动。

对未被本次请求提及的旧字段处理：overwrite会直接删除这些字段；merge会完整保留这些字段
触发条件：overwrite是set操作的默认行为，无需额外配置；merge必须显式开启开关才会生效
适用场景：overwrite适合需要整体替换全文档内容的场景；merge适合只需要更新部分字段、避免误删其他已有数据的场景，还能防止其他客户端的并发更新被意外覆盖
对同名字段的处理：二者逻辑一致，只要是本次请求中明确传值的字段，都会覆盖掉原有旧值

对应你提到的官方规则：

如果文档已存在，其内容将被新提供的数据overwrite，除非你指定将数据merge到现有文档中

这句话的本质是：set操作默认会做整文档替换，只有主动开启merge模式，才会变成“仅更新传入字段、保留其他旧数据”的效果。很多人觉得二者没有区别，往往是测试时传入的字段刚好和原文档字段完全一致，这时候两种操作的执行结果看起来没有差异；只要传入的字段数量少于原文档，差异会立刻显现出来。

内容的提问来源于stack exchange，提问作者karmstr7