Shopware 6：如何通过API增改完整CMS页面并实现跨环境同步？

核心结论 #

完全可以通过单个API请求完成完整CMS页面的添加/更新，无需拆分请求到section、block、slot层级，推荐使用Shopware的sync操作来实现跨环境同步需求。

sync操作的JSON格式示例 #

sync操作支持在一个请求中批量处理多类型实体，通过嵌套结构直接关联CMS页面的所有层级组件，使用upsert动作即可同时覆盖新增和更新场景。以下是完整请求结构：

{
  "action": "sync",
  "entity": "sync",
  "payload": [
    {
      "entity": "cms_page",
      "action": "upsert",
      "payload": {
        "name": "跨环境同步首页",
        "type": "product_list",
        "active": true,
        "sections": [
          {
            "position": 1,
            "type": "default",
            "blocks": [
              {
                "position": 1,
                "type": "image-text",
                "slots": [
                  {
                    "position": 1,
                    "type": "image",
                    "config": {
                      "media": {
                        "source": "static",
                        "value": "your-media-uuid"
                      }
                    }
                  },
                  {
                    "position": 2,
                    "type": "text",
                    "config": {
                      "content": {
                        "source": "static",
                        "value": "同步的文本内容"
                      }
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
}

关键注意事项 #

• 动作选择：upsert会自动判断目标环境是否存在对应CMS页面（通过ID或唯一标识匹配），存在则更新，不存在则创建
• 层级关联：无需提前创建sections、blocks、slots，直接嵌套在cms_page的payload中即可，Shopware会自动处理层级关联关系
• 媒体同步：若页面包含媒体资源，需确保目标环境已有对应媒体的UUID，或在同一个sync请求中同步媒体实体
• 结构复用：可从源环境导出目标CMS页面的完整实体结构（通过后台API调试工具或导出功能），调整后直接用于跨环境同步

不推荐的拆分请求方案 #

若不使用sync操作，确实需要分步骤发起请求：先创建CMS页面，再依次创建sections、blocks、slots，每个步骤都需传递父级实体的ID。这种方式效率低、易出错，完全不适合跨环境同步场景。

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