为何PHP cURL调用Firestore REST API的PATCH请求会替换整个文档？

我完全懂你现在的困扰——明明指定了PATCH请求，结果却跟PUT一样把整个文档给覆盖了。这其实是Firestore REST API的一个特定规则：要实现部分字段更新，必须明确指定updateMask参数，不然Firestore会默认把你的请求当成全量替换操作来处理。

下面给你一步步梳理排查和修正的方案：

1. 核心问题：缺少updateMask参数 #

Firestore的PATCH请求需要明确知道你要更新哪些字段，所以必须在请求URL中添加updateMask参数，用逗号分隔要更新的字段名（嵌套字段用.分隔，比如profile.email）。

举个例子，原本的文档请求URL是：

https://firestore.googleapis.com/v1/projects/[你的项目ID]/databases/(default)/documents/[集合名]/[文档ID]

你需要修改成带updateMask的版本：

https://firestore.googleapis.com/v1/projects/[你的项目ID]/databases/(default)/documents/[集合名]/[文档ID]?updateMask=field1,field2,profile.name

2. 检查请求体格式是否正确 #

请求体里只需要包含你要更新的字段，而且必须遵循Firestore REST API的字段格式——每个字段都要指定类型值（比如stringValue、integerValue），不能直接传原始值。

比如你要更新username和age字段，请求体应该是这样：

{
  "fields": {
    "username": { "stringValue": "new_username" },
    "age": { "integerValue": 30 }
  }
}

3. 修正后的完整PHP cURL代码 #

把上面的要点整合到你的代码里，修正后的示例如下：

// 定义要更新的字段列表，用于生成updateMask参数
$updateFields = ['username', 'age'];
$updateMask = implode(',', $updateFields);

// 构造带updateMask的请求URL
$url = "https://firestore.googleapis.com/v1/projects/你的项目ID/databases/(default)/documents/你的集合名/你的文档ID?updateMask={$updateMask}";

// 构造符合Firestore格式的请求体
$data = [
    'fields' => [
        'username' => ['stringValue' => 'new_user'],
        'age' => ['integerValue' => 30]
    ]
];
$jsonData = json_encode($data);

// 初始化cURL
$curl = curl_init($url);

// 设置cURL选项
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer 你的访问令牌', // 务必添加授权头，否则请求会被拒绝
        'Content-Length: ' . strlen($jsonData)
    ],
    CURLOPT_POSTFIELDS => $jsonData // 传递构造好的请求体
]);

// 执行请求并处理响应
$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL错误 #:" . $err;
} else {
    echo $response;
}

几个关键注意事项 #

• 授权头不能忘：一定要添加Authorization: Bearer 你的访问令牌，你可以通过服务账号密钥生成令牌，或者用OAuth 2.0流程获取。
• 嵌套字段的处理：如果要更新嵌套字段（比如user.profile.email），updateMask里要写user.profile.email，请求体也要对应嵌套结构：

  {
    "fields": {
      "user": {
        "mapValue": {
          "fields": {
            "profile": {
              "mapValue": {
                "fields": {
                  "email": { "stringValue": "new@example.com" }
                }
              }
            }
          }
        }
      }
    }
  }
  

• 为什么之前会全量替换：Firestore的PATCH请求如果没有指定updateMask，会默认把请求体内容当成整个文档的新状态，效果就和PUT完全一样了，所以updateMask是实现部分更新的核心。

内容的提问来源于stack exchange，提问作者Curtis V. Schleich