上传商品图片后进度条停住、出现红色错误，或保存商品后图片消失。先拿一张尺寸较小、文件名只含英文数字的 JPG 做基准测试，再与失败图片比较，避免同时排查格式、大小和权限。

先看上传请求的真实返回

打开 Network，重新上传，找到 media/upload 请求。常见结果：

  • 413：Nginx/代理限制请求体；
  • 500：PHP 或图片处理异常；
  • 403：WAF、后台 Session 或 Form Key；
  • 200 但 JSON 含 error：Magento 校验或文件移动失败。

保存响应 body 与 request ID，再检查同一时间的日志。

核对 PHP 和 Web Server 限制

php -i | egrep 'upload_max_filesize|post_max_size|max_file_uploads|upload_tmp_dir|memory_limit'
php-fpm -i | egrep 'upload_max_filesize|post_max_size|upload_tmp_dir'
nginx -T | grep -n client_max_body_size

CLI PHP 与 PHP-FPM 可能读取不同 php.ini，应以处理上传请求的 FPM 为准。post_max_size 必须大于单文件限制和完整表单开销，修改后平滑重载 FPM/Nginx。

检查临时目录和媒体目录是否可写

php -r 'echo sys_get_temp_dir(), PHP_EOL;'
namei -l pub/media/catalog/product
sudo -u www-data test -w pub/media/catalog/product && echo writable
find pub/media/catalog/product -maxdepth 2 -type d ! -perm -g+w | head

不要用 chmod -R 777。统一部署用户与 PHP-FPM 用户的 group，目录给 group 写入和 setgid，文件保持最小权限。对象存储环境还要检查远程存储凭据与同步队列。

用失败文件单独测试图片处理

file /tmp/problem.jpg
identify /tmp/problem.jpg
php -m | egrep 'gd|imagick|exif'
identify -verbose /tmp/problem.jpg | head -n 40

超大像素图片即使文件只有几 MB，解码后也会占用大量内存。损坏的 ICC/EXIF、CMYK JPEG 或不受支持的 WebP/AVIF 也可能失败。先用受支持格式重新编码副本验证，不要覆盖客户原图。

上传成功但保存后消失

SELECT value_id, value, media_type, disabled
FROM catalog_product_entity_media_gallery
WHERE value LIKE '%problem%';

临时文件上传成功、商品保存时移动失败，通常与 media 临时目录、权限或自定义 product save observer 有关。检查保存 POST 是否 500，并对比 pub/media/tmp/catalog/product 与正式目录。

最后用两张图验证：一张小 JPG，一张接近允许上限的图片。上传、设置主图、保存、重新打开后台、前台生成新缩略图均成功，才算完整修复。