商品图片上传成功但前台不显示，常见现象包括占位图、图片 URL 404、后台有图但列表页无图，或者只有某个 store view 异常。排查时先复制前台实际图片 URL，不要只看后台缩略图。

检查图片角色和商店范围

确认图片已分配到 Base、Small、Thumbnail 等需要的角色，并且没有在当前 store view 使用“无图片”覆盖。可配置商品还要确认前台展示的是父商品图片还是子商品图片。

确认原始文件存在

商品原图通常位于 pub/media/catalog/product。从数据库记录的相对路径定位文件：

SELECT cpe.sku, cpev.value AS image_path
FROM catalog_product_entity_varchar cpev
JOIN catalog_product_entity cpe ON cpe.entity_id = cpev.entity_id
JOIN eav_attribute ea ON ea.attribute_id = cpev.attribute_id
WHERE ea.attribute_code = 'image'
  AND cpe.sku = 'TEST-SKU';

不同 Magento 版本的实体关联字段可能不同，执行前先核对表结构。文件不存在时，应检查上传目录、共享存储挂载和部署流程，不要伪造数据库路径。

重新生成图片缓存

bin/magento catalog:images:resize
bin/magento cache:clean block_html full_page

大量图片重新生成会消耗 CPU 和磁盘 IO，生产环境应在低峰执行并监控空间。若命令报错，重点检查原图格式、损坏文件和 PHP 图像扩展。

检查权限和 Web 路由

find pub/media/catalog/product -type d ! -perm -u+rwx -print
find pub/media/catalog/product -type f ! -perm -u+r -print

不要为了省事把目录改成 777。正确做法是让部署用户、CLI 用户和 Web 用户使用一致的用户组，并按项目部署策略设置目录与文件权限。

远程存储和 CDN

如果使用对象存储或 CDN，确认原图已同步、缓存 URL 指向正确的媒体域名，并检查大小写差异。Linux 文件系统区分大小写，本地开发环境正常不代表生产环境正常。

验证

  1. 直接访问原图 URL，确认不是 404 或 403。
  2. 访问生成后的缓存图片 URL。
  3. 分别检查商品详情页、分类页和搜索结果页。
  4. 切换 store view，确认图片角色没有被范围配置覆盖。
  5. 更新一张测试图片，确认后续上传流程能够自动生效。