通过Postman发送PUT请求更新Contentful条目时字段全部清空如何解决？

你遇到的字段清空问题本质是混用了Contentful交付API（CDA）和管理API（CMA）的字段格式，且请求体结构不符合管理API的要求，具体排查解决步骤如下：

排查步骤1：修正请求体基础结构 #

你调用https://cdn.contentful.com（交付API）拿到的响应是分页包裹的数组结构，整个返回结果的顶级是Array类型，包含total、items、includes等分页字段，不能直接作为PUT请求的请求体。你需要先提取items[0]（即你要修改的单个条目对象）作为请求体的基础，丢弃外层的分页相关字段。

排查步骤2：调整fields字段格式（最关键） #

交付API为了简化返回，会自动按请求的locale扁平化字段，返回格式是"字段名": "值"，但管理API要求所有字段必须明确指定locale，格式为"字段名": {"locale代码": "对应值"}。
以你示例中的字段为例，原交付API返回的：

"fields": {
  "name": "Test entry",
  "slug": "test-entry"
}

需要调整为管理API要求的格式：

"fields": {
  "name": {
    "en-US": "Test entry 123"
  },
  "slug": {
    "en-US": "test-entry"
  },
  // 剩余所有字段都按照该格式补全
}

所有字段都要按上述嵌套格式调整，否则管理API会认为你没有提交任何字段值，直接清空现有内容。

排查步骤3：校验请求头和版本号 #

• 确认Authorization请求头格式为Bearer 你生成的Personal Access Token，不要遗漏Bearer前缀
• 确认X-Contentful-Version的值和你获取条目时拿到的sys.revision值一致（你示例中为3），如果提交前条目被其他操作修改过，需要重新获取最新的版本号再提交

排查步骤4：清理请求体多余字段 #

管理API会自动生成所有sys下的属性，你不需要在请求体中携带任何sys相关字段，只需要保留metadata和调整好格式的fields两个顶级字段即可，避免多余字段触发校验异常。

正确的PUT请求体示例参考 #

{
  "metadata": {
    "tags": []
  },
  "fields": {
    "name": {
      "en-US": "Test entry 123"
    },
    "slug": {
      "en-US": "test-entry"
    },
    "address": {
      "en-US": "Lviv"
    },
    "cityName": {
      "en-US": "Lviv"
    },
    "phone": {
      "en-US": "+380931231212"
    },
    "coordinates": {
      "en-US": {
        "lon": -115.302,
        "lat": 36.18709
      }
    },
    "dog": {
      "en-US": "100"
    },
    "cat": {
      "en-US": "100"
    },
    "delivery": {
      "en-US": "100"
    },
    "photo": {
      "en-US": [
        {
          "sys": {
            "type": "Link",
            "linkType": "Asset",
            "id": "2hSnYhQDJzU99NvlsYdk3k"
          }
        }
      ]
    },
    "additionalInfo": {
      "en-US": {
        "data": {},
        "content": [
          {
            "data": {},
            "content": [
              {
                "data": {},
                "marks": [],
                "value": "Test",
                "nodeType": "text"
              }
            ],
            "nodeType": "paragraph"
          }
        ],
        "nodeType": "document"
      }
    },
    "featuredHotel": {
      "en-US": true
    },
    "phoneClicks": {
      "en-US": 1
    }
  }
}

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