发布后商品页 HTML 正常，所有缩略图却 404。先不要重新上传商品图片：Magento 原图通常在 pub/media/catalog/product，前台 URL 可能指向按尺寸生成的缓存路径。原图存在而派生图缺失，与原图本身丢失是两类事故。

从一个失败 URL 反查

记录请求状态、响应服务器和路径；在媒体存储中找到对应原图。原图也不存在，检查共享存储挂载、发布脚本是否错误清理 media；原图存在，查派生生成、权限和 rewrite。

bin/magento config:show web/unsecure/base_media_url
bin/magento config:show web/secure/base_media_url
find pub/media/catalog/product -type f -name 'example.jpg'

Media 不应跟 release 一起被替换

蓝绿发布若每个 release 有独立 pub/media，却没有正确共享链接，新 release 会看到空目录。构建脚本可以清 pub/static，但不应递归删除客户上传的 media。核对软链接目标、挂载时机和运行用户。

缓存生成需要写权限

首次请求或预生成任务需要在 media cache 下创建目录和文件。PHP-FPM 用户与部署用户不一致、只读容器或 umask 错误，会导致 404/500。不要用 777 作为长期修复，应设置明确 owner/group 和最小写权限。

Web server 与远程存储

Nginx 示例配置会把不存在的缓存图交给 Magento 生成；自定义 location 顺序错误可能直接返回 404。使用对象存储/CDN 时，还要确认派生文件同步策略、origin path 和大小写。

修复后测试已有缓存图、新尺寸首次生成、后台上传新图、图片删除和 CDN purge。对比原图与派生图路径，确保下一次发布不会再次切断 media。

数据库记录与文件路径

查询 catalog_product_entity_media_gallery 及关联值，确认 value 路径与磁盘大小写完全一致。数据库有记录、文件缺失，可能是媒体迁移不完整；文件存在但记录指向旧扩展名，缓存生成也找不到。批量修复前导出 SKU—路径映射。

缓存清理的正确范围

删除派生缓存可以让 Magento 重建，但不要删除原图目录。大目录一次递归删除会产生 I/O 峰值，随后所有请求同时生成缩略图形成惊群。可在发布前按常用尺寸预热，并限制并发。

图片处理依赖

GD/Imagick 缺扩展、内存不足、超大原图或损坏 ICC 信息可能只让某些图片生成失败。查看 PHP 图像库、错误日志和单个原图尺寸，用问题文件在隔离环境复现，不能把全部 404 都归为权限。

部署健康检查要覆盖一张新图

只访问已有 CDN 缓存图无法发现源站生成权限问题。发布后上传或选择一张从未生成过目标尺寸的测试图片，请求缩略图并校验 Content-Type、尺寸和缓存头；随后删除测试数据。这样能同时验证 media 挂载、PHP 图像库、rewrite 与 CDN 回源。