Shopware 6 如何通过REST API实现多图片上传

前置准备 #

• 先获取API访问凭证：进入Shopware后台「设置」>「系统」>「集成」创建新集成，生成Client ID和Client Secret，申请带write权限的Bearer Token
• 提前确认图片要关联的目标实体ID（如产品ID、分类ID），准备好所有待上传图片的二进制流/本地存储路径

两种可落地的实现方案 #

方案一：单请求单图片并行批量上传（原生环境推荐，稳定性最高） #

注意：Shopware 6 原生REST API暂不支持单请求上传多个二进制文件，该方案是原生环境下容错性最高的实现方式。

单张图片上传请求规范

• 请求方法：POST
• 请求地址：/api/_action/media/upload
• 必传请求头：
  • Authorization: Bearer <你申请的访问Token>
  • Content-Type: image/<图片实际格式，如jpeg、png>
  • Accept: application/json
• Query参数说明：

  参数名	说明	示例值
  extension	图片文件后缀	jpg
  fileName	自定义文件名（无需带后缀）	product-spu-001-1
  mediaFolderId	媒体库目标文件夹ID，可选，不传默认存入根文件夹	6f7a2d...
  entityId	要关联的目标实体ID	5a8c3f...
  entityName	目标实体类型，产品填product、分类填category	product

• 请求体：直接传入图片的二进制流即可

批量处理逻辑

将所有待上传图片拼接为请求列表，用并发请求工具（如Guzzle并发请求、JS的Promise.all）批量发起请求，建议控制并发数不超过10，避免触发API限流。单张上传成功后会返回对应mediaId，可留存后续做封面设置、排序调整等操作。

方案二：先批量创建媒体占位再上传内容（适合需要预占媒体ID的场景） #

步骤1：批量创建媒体占位记录

• 请求方法：POST
• 请求地址：/api/media
• 请求头：Authorization: Bearer <你的访问Token>、Content-Type: application/json
• 请求体示例（批量创建3个占位）：

[
  {
    "mediaFolderId": "<目标文件夹ID>",
    "fileName": "product-spu-001-1"
  },
  {
    "mediaFolderId": "<目标文件夹ID>",
    "fileName": "product-spu-001-2"
  },
  {
    "mediaFolderId": "<目标文件夹ID>",
    "fileName": "product-spu-001-3"
  }
]

请求成功后会返回每个占位对应的mediaId，全部留存备用。

步骤2：批量上传图片内容到对应占位

对每个mediaId单独发起上传请求：

• 请求方法：POST
• 请求地址：/api/_action/media/<mediaId>/upload
• 请求头：Authorization: Bearer <你的访问Token>、Content-Type: image/<图片格式>
• Query参数：extension=<图片后缀>
• 请求体：对应图片的二进制流

步骤3：批量关联到目标实体

如果创建占位时没有直接关联实体，所有图片上传完成后发起批量更新实体的请求，将mediaId关联到对应实体的媒体字段即可。

常见问题处理 #

• 上传大于2M的图片前，先调整PHP的upload_max_filesize和post_max_size配置，避免上传被服务端拦截
• 无需自行处理重名问题，Shopware遇到重复文件名时会自动加数字后缀区分
• 需要设置封面图的话，更新目标实体的coverId字段为对应图片的mediaId即可

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