WordPress 上传图片报错：明明是 PNG，却提示「请转换为 JPEG 或 PNG 格式」？

背景

在媒体库上传图片一切正常，但在文章编辑器中上传时，却突然报错：

{"code": "rest_upload_image_type_not_supported","message": "Web 服务器无法为该图像生成响应式图像大小。请在上传前将其转换为 JPEG 或 PNG 格式。"
}

明明上传的就是 PNG 啊？🤔
WordPress 这次又在搞什么幺蛾子？

---

一、问题复现：媒体库能传，文章里不行？

这个坑非常诡异：

• ✅ 在「媒体库」中手动上传图片，一切正常；
• ❌ 在文章中直接插入图片，就报错；
• ✅ 图片格式确实是 image/png；
• ❌ 错误提示却说「请转换为 JPEG 或 PNG」。

这说明：

WordPress 的 REST API 在生成响应式图像尺寸时失败了，也就是说——不是上传的问题，而是「生成缩略图」阶段崩了。

---

二、排查过程：从「PHP 图像扩展」入手

WordPress 生成缩略图时，底层依赖两种图像处理引擎：

图像处理引擎	PHP 扩展名	作用
GD Library	php-gd	轻量，支持常见 PNG/JPEG
ImageMagick	php-imagick	功能强，支持 WebP、HEIC、AVIF 等

只要这两个之一能用，WordPress 就能生成多尺寸缩略图。

于是执行检查命令：

php -m | egrep -i 'gd|imagick'

结果 😶 —— 没有任何输出。

至此可以确定：
服务器根本没有启用任何图像处理扩展。

---

三、罪魁祸首：PHP-FPM 没加载 GD

接着我查系统服务：

systemctl status php8.3-fpm

发现系统中存在两个 FPM 池（www 和 th333），这就意味着：

• CLI（命令行执行 php）和 FPM（WordPress 实际执行）使用的是不同的配置文件；
• CLI 侧就算安装了 GD，FPM 池没加载，也一样会报错；
• WordPress 在文章中上传图片，是通过 REST API（FPM 执行）——因此出错。

---

四、修复步骤：让 FPM 加载 GD + Imagick

以 Ubuntu / Debian 为例，执行以下命令即可：

sudo apt-get update
sudo apt-get install -y php8.3-gd php8.3-imagick
sudo systemctl restart php8.3-fpm
sudo systemctl restart nginx

验证是否安装成功：

php -i | grep -A3 "gd support"
# 或在网页中放一个 phpinfo.php

应看到：

GD Support => enabled
PNG Support => enabled

大功告成。

---

五、原理揭秘：为什么媒体库没事？

WordPress 在两种场景下处理图片的方式不同：

场景	触发方式	图像生成逻辑
媒体库上传	后台表单上传	不会立刻生成响应式图像
文章编辑器上传	REST API (/wp-json/wp/v2/media)	会实时生成多尺寸缩略图

当 PHP 缺少图像扩展时：

• 媒体库上传只是把文件存进去；
• 而文章中上传必须生成 responsive image；
• 缺扩展 → 生成失败 → rest_upload_image_type_not_supported。

---

六、最佳实践：防止再次踩坑

1. 同时安装并启用 GD 与 Imagick

   sudo apt-get install -y php8.3-gd php8.3-imagick
   

2. 在 wp-config.php 中优先使用 GD

   define('WP_IMAGE_EDITORS', ['WP_Image_Editor_GD', 'WP_Image_Editor_Imagick']);
   

3. 确认 FPM 池共享相同的 php.ini

   grep "listen" /etc/php/8.3/fpm/pool.d/*.conf
   

   确保所有站点都跑在已启用扩展的池上。

4. 重启 FPM 与 Web

   sudo systemctl restart php8.3-fpm nginx
   

---

七、写在最后

这次的问题看似是「图片格式不支持」，实际上是 PHP 环境缺少图像处理能力。
媒体库之所以没问题，是因为那一步根本没触发缩略图生成。

WordPress 提示你「请转换为 JPEG 或 PNG」只是个假象，
真正的原因是：你的 PHP 不知道该怎么生成它。

所以，下次再遇到这种莫名其妙的格式错误，别急着怀疑图片，
先查查 GD 和 Imagick 在不在。

---

如果这篇文章帮你解决了问题，记得：
点赞 + 收藏 + 关注 🔥
我会继续更新更多实战型踩坑记录，让每一次「为什么？」都有答案。

---