通过API在Shopware 6中添加带图产品并加购：媒体图片上传失败求助

一、媒体资产上传与产品关联的正确流程 #

你当前的核心问题大概率是没遵循Shopware媒体资产的完整创建链路——必须先上传文件生成媒体实体，再将其与产品关联，而非直接在产品创建时嵌入文件。

1. 先创建媒体文件夹（可选但推荐） #

通过API创建专属文件夹管理产品图片，避免媒体文件混乱：

# POST /api/media-folder
{
  "name": "Product Images",
  "parentId": "<root-folder-id>"  # 可通过GET /api/media-folder获取根目录ID
}

2. 上传媒体文件生成媒体实体 #

必须用multipart/form-data请求，发送到/api/_action/media/upload，参数包括：

• file: 本地图片文件（如test.jpg）
• folderId: 步骤1创建的文件夹ID（或现有合法文件夹ID）
• fileName: 自定义文件名（可选，默认用原文件名）

请求成功后，响应会返回mediaId，务必保存这个ID用于后续关联。

3. 将媒体关联到产品 #

方案A：创建产品时直接关联

在POST /api/product的请求体中加入media字段：

{
  "name": "Test Product",
  "price": [{"currencyId": "<default-currency-id>", "gross": 99.99, "net": 80.00, "linked": true}],
  "stock": 10,
  "media": [
    {
      "mediaId": "<步骤2获取的mediaId>",
      "position": 1,
      "main": true  # 设置为产品主图
    }
  ]
}

方案B：给已存在的产品追加媒体

用PATCH请求更新产品，注意如果产品已有媒体，直接传media会替换现有关联；如需追加，需先GET产品的现有媒体列表，再合并新条目：

# PATCH /api/product/<product-id>
{
  "media": [
    # 这里可以包含原有媒体条目 + 新的mediaId条目
    {
      "mediaId": "<new-mediaId>",
      "position": 2,
      "main": false
    }
  ]
}

上传失败常见排查点 #

• 确认请求头是multipart/form-data，而非application/json
• 检查文件大小是否超过Shopware后台设置的上传限制（路径：设置>系统>文件上传）
• 验证folderId是否有效，且当前API用户有媒体写入权限
• 确认图片格式为Shopware允许的类型（如jpg/png，后台可配置）

二、将带图产品加入购物车 #

产品关联媒体后，通过购物车API完成添加：

1. 获取或创建购物车Token #

匿名用户直接创建购物车：

# POST /api/checkout/cart
{
  "name": "default"
}

响应中的token即为购物车ID，后续请求需用到。

2. 添加产品到购物车 #

# POST /api/checkout/cart/<cart-token>/line-item
{
  "type": "product",
  "referencedId": "<product-id>",
  "quantity": 1
}

自定义插件中媒体上传的注意事项 #

如果是在插件代码中处理，不要直接调用API，用Shopware内置服务更可靠：

1. 注入MediaService完成文件上传：

use Shopware\Core\Content\Media\MediaService;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\HttpFoundation\File\UploadedFile;

class ProductMediaUploader
{
    private MediaService $mediaService;

    public function __construct(MediaService $mediaService)
    {
        $this->mediaService = $mediaService;
    }

    public function upload(string $filePath, string $folderId, Context $context): string
    {
        $uploadedFile = new UploadedFile(
            $filePath,
            basename($filePath),
            mime_content_type($filePath),
            filesize($filePath),
            UPLOAD_ERR_OK,
            true
        );

        $mediaId = Uuid::randomHex();
        $this->mediaService->upload($uploadedFile, $folderId, $mediaId, $context);

        return $mediaId;
    }
}

2. 用ProductRepository关联媒体到产品：

use Shopware\Core\Framework\DataAbstractionLayer\RepositoryInterface;

$productRepository->update([
    [
        'id' => $productId,
        'media' => [
            [
                'mediaId' => $mediaId,
                'position' => 1,
                'main' => true
            ]
        ]
    ]
], $context);

3. 插件权限配置：在plugin.xml中添加content_media:write权限，确保操作合法。

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