如何通过Sanity HTTP API正确添加引用数组？

问题根源 #

你遇到的报错是因为操作数组时使用了不符合Sanity规范的路径或更新方式，导致Studio无法正确解析文档结构。以下是两种可靠的实现方式：

方式1：替换整个引用数组（初始化/全量更新） #

使用set操作符直接覆盖tags字段，适合需要完全更新数组内容的场景：

• 请求方法：PATCH
• 请求URL：https://<你的项目ID>.api.sanity.io/v2021-06-07/data/mutate/<数据集名称>
• 请求体（JSON）：

{
  "mutations": [
    {
      "patch": {
        "id": "<目标文档ID>",
        "set": {
          "tags": [
            { "_ref": "<标签文档ID1>", "_type": "reference" },
            { "_ref": "<标签文档ID2>", "_type": "reference" }
          ]
        }
      }
    }
  ]
}

注意：每个引用必须包含_ref（目标文档ID）和_type: "reference"，这是Sanity引用的标准格式。

方式2：向已有数组追加引用（增量更新） #

使用append操作符在现有数组末尾添加新引用，适合不需要覆盖原有内容的场景：

• 请求体（JSON）：

{
  "mutations": [
    {
      "patch": {
        "id": "<目标文档ID>",
        "append": {
          "tags": [
            { "_ref": "<新增标签文档ID>", "_type": "reference" }
          ]
        }
      }
    }
  ]
}

关键注意事项 #

1. Schema校验：确保你的文档Schema中tags字段定义正确，示例如下：

export default {
  name: 'post',
  type: 'document',
  fields: [
    // 其他字段...
    {
      name: 'tags',
      type: 'array',
      of: [{ type: 'reference', to: [{ type: 'tag' }] }]
    }
  ]
}

2. 避免错误路径：不要使用tags[]这类非标准路径写法，必须通过Sanity官方支持的set/append/prepend等操作符操作数组。
3. 验证mutation结果：即使返回状态码200，也要检查响应体的results字段，确认mutation是否真正成功——部分隐性错误不会改变状态码，但会在结果中提示。

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