商品图片批量导入有一个很典型的误区：把图片直接放进 pub/media/catalog/product，然后在CSV里写完整磁盘路径。实际上，新图片应该从导入目录或可访问的远程URL进入，Magento会自己整理最终的媒体目录。

最省事的文件结构

如果可以通过SFTP上传文件，建议在Magento根目录下准备：

var/import/images/product_images/
├── SKU-100-main.jpg
├── SKU-100-side.jpg
├── SKU-100-back.jpg
└── SKU-200-main.jpg

然后CSV只保留SKU和图片相关列。更新现有商品图片时，不需要再次提交名称、价格、分类等无关字段。

sku,base_image,small_image,thumbnail_image,additional_images
SKU-100,SKU-100-main.jpg,SKU-100-main.jpg,SKU-100-main.jpg,"SKU-100-side.jpg,SKU-100-back.jpg"
SKU-200,SKU-200-main.jpg,SKU-200-main.jpg,SKU-200-main.jpg,

base_image 是商品详情主图，small_image 常用于列表，thumbnail_image 常用于缩略图区域，additional_images 放附加图片。多个附加图用多值分隔符分开，因为字段本身含逗号，CSV工具通常会自动加双引号。

Images File Directory到底填什么

后台进入 System > Data Transfer > Import，Entity Type选择Products。图片文件放在默认 var/import/images 时，Images File Directory可以留空；如果放在子目录 var/import/images/product_images，填写 product_images 或按当前版本页面要求填写相对目录。

不要在CSV文件名里重复写 var/import/images，也不要使用服务器绝对路径。最简单的判断方式是：导入页面中的图片目录与CSV文件名拼起来，应能定位到实际文件。

也可以直接使用远程图片URL

如果图片在一个无需登录即可访问的HTTPS地址，可以在图片列中填完整URL：

sku,base_image,small_image,thumbnail_image
SKU-300,https://static.example.com/products/SKU-300.jpg,https://static.example.com/products/SKU-300.jpg,https://static.example.com/products/SKU-300.jpg

远程方式不需要先SFTP上传，但服务器必须能够访问该URL。防盗链、临时签名、登录验证、超时、证书问题或来源服务器限制，都可能导致下载失败。数据量大时，本地导入目录通常更稳定。

文件名建议在导入前统一

  • 统一使用小写扩展名，例如 .jpg 或 .webp。
  • 避免中文空格、括号、井号和过长文件名。
  • 同一批次保持大小写一致，Linux服务器区分大小写。
  • 用SKU作为文件名前缀，出错时容易反查。
  • 在CSV生成前检查重复文件名和缺失文件。

导入成功但前台仍没图

先在后台商品页面确认图片是否进入Media Gallery。如果后台有图、前台没有，检查缓存、主题图片尺寸配置、文件权限以及按需缩图请求是否正常。图片导入本身不会替你提前生成所有尺寸，前台第一次请求时才可能创建缓存图。

如果后台也没有图，查看Import History中的错误文件，常见信息包括本地文件不存在、远程资源无法下载、目录不可读。此时不要反复导入同一大文件，先挑一个SKU和一张图单独测试。

替换图片时要注意旧图

给 base_image 填一个新文件名，会把新图设为主图，但不一定自动删除媒体库中的旧图。如果业务要求彻底清理旧图片，需要先明确是只改变角色、排除旧图，还是删除旧媒体记录。不要在生产环境直接批量删除 pub/media 文件。

大批量操作前，建议先导出现有商品的图片字段留档。完成后抽查主图、列表图、缩略图、附加图顺序，以及不同Store View是否使用了预期图片。

图片数量多、命名不统一或需要从旧站迁移时，可以先做文件清单与SKU映射。需要协助整理图片目录、生成CSV并验证前台效果，欢迎联系我们。