WordPress 媒体库上传图片时只显示“HTTP 错误”，信息看起来很少，但故障通常落在两个阶段：请求还没完整交给 WordPress 就被 PHP、Web 服务器或安全规则拒绝；或者原图已经保存，WordPress 在读取图片、生成缩略图时失败。
排查时先判断失败发生在哪个阶段，再检查对应配置。直接反复修改 upload_max_filesize，经常会漏掉反向代理限制、临时目录权限、Imagick/GD 资源不足等问题。
先用一张小 JPEG 确认故障范围
准备一张经过正常导出的 JPEG 测试图，建议控制在 500 KB 左右、宽高不超过 1600 像素，文件名只用英文、数字和短横线。打开浏览器开发者工具的 Network（网络）面板，再从“媒体库 → 添加媒体文件”上传。
重点看上传请求的状态码和响应内容：
- 小图也失败，并返回
413：优先检查 Nginx、Apache、CDN/WAF 或托管平台的请求体大小限制。 - 小图成功，大图失败：检查 PHP 上传限制、内存和图片像素尺寸。
- 返回
403：检查 WAF、安全插件、主机防火墙或 ModSecurity 规则。 - 返回
500、502、504：查看 PHP、Web 服务器和反向代理错误日志，留意内存耗尽、进程超时或上游连接中断。 - 上传后媒体库里出现原图，但没有缩略图，或者稍后才报错：重点检查图片处理库、可用内存和缩略图生成过程。
如果 Network 面板只看到 WordPress 的通用提示，不要凭提示文字猜原因。记录请求 URL、状态码、响应时间和服务器返回内容，再和同一时间点的日志对应。
检查网站实际生效的 PHP 上传参数
WordPress 显示的最大上传大小取 upload_max_filesize 与 post_max_size 中较小的值。只修改其中一项不会提高最终限制。PHP 官方文档还要求 post_max_size 大于 upload_max_filesize，并建议 memory_limit 大于 post_max_size。
需要核对的参数包括：
file_uploads = On
upload_max_filesize = 32M
post_max_size = 40M
memory_limit = 256M
upload_tmp_dir = /path/to/php-upload-tmp
上面的数值只是配置示例，应该按网站实际图片尺寸、插件数量和主机资源调整。还要确认“当前处理 WordPress 请求的 PHP”读取了哪份配置。命令行 PHP、Apache 模块、PHP-FPM 以及不同 PHP 版本，可能使用不同的 php.ini。
可在 WordPress“工具 → 站点健康 → 信息 → 服务器”中先查看 PHP 与上传信息。拥有服务器权限时，再检查对应 PHP-FPM 池、虚拟主机或主机面板里的生效值。修改后要按环境重载 PHP-FPM 或 Web 服务，并回到站点健康页面确认数值已经变化。
当上传内容超过 post_max_size 时，PHP 可能让 $_POST 和 $_FILES 变为空，WordPress 因此拿不到可解释的上传错误。此时后台看到的提示往往比真实原因更模糊。
检查 Nginx、Apache、CDN 与安全规则
图片到达 PHP 之前，可能已经被入口层挡住。使用 Nginx 时检查虚拟主机和对应 location 是否设置了 client_max_body_size：
server {
client_max_body_size 40m;
}
Nginx 官方文档说明，请求体超过该值时会返回 413 Request Entity Too Large。配置可能出现在 http、server 或 location 层级，内层设置会影响最终结果。修改后先执行配置测试，再平滑重载：
sudo nginx -t
sudo systemctl reload nginx
Apache 环境则检查 LimitRequestBody，同时核对虚拟主机、目录配置和 .htaccess。如果站点前面还有 CDN、负载均衡、WAF 或主机面板，它们也可能设置独立的上传上限或安全策略。
不要为了让上传通过而直接关闭全部安全防护。先根据时间、请求路径和规则编号定位拦截项，再为 WordPress 上传接口做最小范围调整。常见相关路径包括 async-upload.php 和 REST API 的媒体端点，具体以浏览器实际请求为准。
检查 PHP 临时目录和 uploads 写入权限
浏览器上传的文件通常先进入 PHP 临时目录，再由 WordPress 移动到 wp-content/uploads/年/月/。这两个位置只要有一个不可写，上传就会失败。
先确认以下问题：
upload_tmp_dir指向的目录是否存在，PHP-FPM 或 Web 服务运行用户是否有写入和进入目录的权限。- 没有显式配置
upload_tmp_dir时，系统默认临时目录是否可用，磁盘空间和 inode 是否充足。 open_basedir是否允许访问临时目录和 WordPress 上传目录。wp-content/uploads的所有者、用户组和权限是否与当前 PHP 运行方式匹配。- 按年月组织上传目录时，WordPress 是否能创建新的月份目录。
在 Linux 服务器上，可以按实际路径检查目录链：
namei -l /var/www/example.com/wp-content/uploads
df -h
df -i
权限修复应以正确的所有者和用户组为主，再赋予所需的最小权限。常见基线是目录 755、文件 644，但 PHP-FPM 独立用户、共享主机和容器挂载的要求可能不同。不要把整个网站或上传目录递归改成 777，这既掩盖所有权问题，也会扩大安全风险。
原图已上传时，检查 Imagick、GD 与缩略图生成
WordPress 接收图片后，会读取图片信息并生成主题、插件和媒体设置注册的多个子尺寸。官方代码中，wp_generate_attachment_metadata() 会创建缩略图和中间尺寸；图片编辑器通常从 Imagick 和 GD 中选择可用实现。这个阶段较慢，也可能因为超时或内存不足而中断。
出现以下现象时，应把重点放到图片处理阶段：
- 媒体库中能看到附件记录或原图文件，但预览为空。
- 只生成了一部分缩略图。
- 小尺寸 JPEG 正常，高像素照片、PNG、WebP 或带特殊色彩配置的图片失败。
- PHP 日志出现
Allowed memory size exhausted、Imagick resource limit、无法读取图片或写入派生文件等错误。
可先将失败图片另存为标准 RGB JPEG，去掉异常 EXIF/ICC 元数据并适当缩小像素尺寸后重试。文件只有几 MB，不代表处理时占用的内存也小；解码后的像素、色彩通道以及同时生成的多个尺寸都会消耗内存。
在“工具 → 站点健康 → 信息 → 媒体处理”中检查服务器是否识别 Imagick 或 GD。拥有命令行权限时，也可以核对 PHP 模块：
php -m | grep -Ei 'imagick|gd'
这条命令只反映当前命令行 PHP。网站使用 PHP-FPM 时，仍需以站点健康信息或对应 FPM 环境为准。
主题和图片优化插件可能注册很多额外尺寸。一次上传要生成的文件越多，处理时间和峰值内存越高。排障阶段可以在测试环境统计已注册尺寸，临时停用不必要的图片优化、WebP 转换、水印或远程存储功能，再上传同一张测试图对比。
逐个排除插件、主题和安全组件
当服务器日志没有直接答案，可在备份或测试环境中做最小化排除：
- 暂停缓存、图片压缩、WebP/AVIF 转换、对象存储、水印和安全类插件。
- 上传同一张基准 JPEG，记录结果。
- 每次只恢复一个插件并重复测试。
- 插件排除后仍失败，再短暂切换到官方默认主题验证。
每次只改变一个变量。一次停用和恢复多项功能，即使上传恢复，也很难判断是哪一项造成了冲突。
安全插件或 WAF 的日志如果记录了规则编号、命中参数和请求路径，应优先按这些证据调整。不要把“上传目录不可写”和“安全规则拦截”混在一起处理，它们在日志和 HTTP 状态码上的表现通常不同。
临时开启 WordPress 调试日志
如果错误发生在 WordPress 或插件执行阶段，可在已有备份的前提下，短时间开启日志并关闭前台显示：
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
这些配置应放在 wp-config.php 中 /* That's all, stop editing! Happy blogging. */ 之前。随后重新上传一张可稳定复现的测试图，检查 wp-content/debug.log，并同时查看 PHP-FPM、Nginx 或 Apache 错误日志。
生产站不适合长期打开调试模式。完成定位后恢复 WP_DEBUG 设置，删除或妥善保护日志文件。日志中可能包含服务器路径、插件信息和请求细节，不能让它通过公网直接访问。
修复后怎样确认问题已经解决
不要以“某一张图上传成功”作为唯一结论。准备三张可控测试图：一张小 JPEG、一张接近日常使用尺寸的 JPEG，以及一张网站经常使用的 PNG 或 WebP。逐张上传后检查：
- 媒体库预览是否正常，附件详情能否打开。
- 上传目录里是否生成了预期的缩略图和中间尺寸。
- 页面插入图片后，前台响应式图片是否能正常加载。
- 浏览器 Network 面板没有
413、403或5xx。 - PHP、Web 服务器和 WordPress 日志没有新增对应错误。
最后记录实际生效的 PHP 上限、入口层请求限制、PHP 运行用户、临时目录位置和图片处理库。以后迁移服务器、切换 PHP 版本或接入 CDN/WAF 时，按这份记录逐项核对，通常比再次从“HTTP 错误”四个字开始猜要快得多。
参考资料
- WordPress Developer Resources：
wp_max_upload_size()，说明 WordPress 取upload_max_filesize与post_max_size的较小值。 - PHP Manual：php.ini 核心配置与文件上传参数，包括
post_max_size、upload_max_filesize、upload_tmp_dir和memory_limit。 - WordPress Developer Resources：
media_handle_upload()、wp_generate_attachment_metadata()、wp_get_image_editor()与wp_image_editors。 - WordPress Advanced Administration Handbook：Debugging in WordPress。
- Nginx 官方文档：
client_max_body_size。 - Apache HTTP Server 2.4 文档：
LimitRequestBody。
资料核验日期：2026-09-23。