Admin API 上传商品图片失败怎么排查

现象#

调用 productCreateMedia 报错或图片一直处于 processing，前台不显示。

原因#

• 直接传了外链 URL，但该 URL 需要登录或禁止外链
• 没有走 staged upload，大文件被拒
• mediaContentType 与实际文件不符
• 图片尺寸或格式不符合要求（如 CMYK JPEG）

处理步骤#

1. 大文件走 stagedUploadsCreate 拿上传地址，POST 文件后再用返回的 resourceUrl 创建 media
2. 确认 mediaContentType: IMAGE，格式为 JPG/PNG/WebP
3. 外链图片先下载再上传，避免防盗链
4. 创建后轮询 media.status，FAILED 时读 mediaErrors

验收标准#

图片上传后状态变为 READY，前台商品页正常展示，无 processing 卡死。