上传文件 500 排查：目录权限、POST 上限与驱动配置的优先级

上传文件报 500 是很多人卡住的地方——看完这篇，你能按「目录权限 → PHP 上限 → 白名单 → 驱动配置」的优先级顺序，十分钟内定位到底是哪一环出的问题，而不是反复改配置碰运气。

先说一个判断原则：500 是服务器内部错误，不是「文件太大」这种业务提示。 如果后台把原因判断出来了（比如超过 PHP 上限、白名单不符、目录不可写），页面通常会直接告诉你是哪一条。所以凡是走到 500，多半是问题发生在这套判断之前，或者发生在写文件的那一刻。

第一步：先确认 500 出现在哪一层

进服务器看错误日志，位置看你用的环境：

• 宝塔面板：网站 → 找到站点 → 日志 → PHP 错误日志
• 其他环境：站点根目录或 PHP 的 error_log，php -i | grep error_log 能查路径

日志里如果有 PHP Fatal error、Allowed memory size exhausted、failed to open stream: Permission denied，直接跳到对应步骤，别往下瞎猜。

注意：如果日志是空的，说明请求根本没走到 PHP（比如 Nginx 转发规则错了），先解决伪静态转发，再回来看日志。

第二步：目录权限（优先级最高）

上传最终要往磁盘写文件，写不进去就是 500。

chown -R www:www /www/wwwroot/bbs/uploads
chmod -R 755 /www/wwwroot/bbs/uploads

宝塔用户直接在「文件 → 上传目录 → 权限」里把所有者设成 www，权限 755 即可。不需要 777。

注意：改权限要改整个上传目录，只改顶层目录不够，子目录（按月份/用户分目录的结构）可能还是旧的属主。用 -R 递归更省事。另外 SELinux 开启的机器还要单独放行，否则权限看着对、照样写不进去。

测完这一步如果还报 500，再用一个最笨的办法验证：新建一个 PHP 文件写入 uploads 目录，能不能成功。能写，说明权限没问题，往下走。

第三步：PHP 的 POST 上限

这是第二个高频原因。宝塔默认 upload_max_filesize 和 post_max_size 都是 2M，而手机随手一张照片就 3-8M。

后台「系统设置 → 上传」里如果配的上传限制比 PHP 上限还大，实际生效的永远是 PHP 那个更小的值。

改法：宝塔「软件商店 → PHP 设置 → 配置修改」，或直接编辑 php.ini：

upload_max_filesize = 32M
post_max_size = 32M
max_execution_time = 120
memory_limit = 256M

保存后必须重启 PHP-FPM，不重启不生效。

注意：post_max_size 一定要 ≥ upload_max_filesize，因为表单里的其他字段也占 POST 体积。只调 upload 不调 post，超过后整个 POST 被丢弃，接口拿不到任何参数，报出来就是一个裸 500。

第四步：后台的两个白名单字段

回到后台「系统设置 → 上传」，这里有两个互相独立的字段：

• 「允许的扩展名」——管图片
• 「附件允许的扩展名」——管附件

很多人只改了前者，然后传 PDF、ZIP 就失败。两个都要按需加上，用英文逗号分隔，不带点号。

注意：这块的问题页面上一般会给出明确提示（白名单不符），不是典型 500 来源。但如果你自定义过上传接口或改过模板，扩展名判断抛异常也可能变成 500，所以排查时顺手核对一下没坏处。

第五步：上传驱动 / 云存储配置

后台「系统设置」里有云存储配置项。如果你开过云存储，上传链路就变成「PHP → 应用 → 远端」，多一环就多一个可能的崩点，而且远端报错往往在本地看不到细节。

排查手法很简单：临时把驱动切回本地存储，传一个几十 KB 的小图。

• 切本地就好了 → 问题在云存储的密钥、Bucket、区域、回调地址上
• 切本地还报 500 → 问题不在驱动，回到第二步重新看权限和日志

注意：切换驱动后先清一次缓存再测（后台「系统工具 → 缓存清理」），避免读到旧的配置副本，白测一轮。

一个速查顺序

顺序的逻辑是：从「影响面最大、改动成本最低」往「局部、需要配置凭证」排。 权限一行命令就改完，云存储要核对一堆密钥，先易后难，避免把简单问题复杂化。

小结

• 500 先看 PHP 错误日志，不要凭感觉改配置。
• 目录属主设为 www、权限 755、递归生效，不用 777。
• upload_max_filesize 和 post_max_size 一起调，改完必须重启 PHP-FPM。
• 后台图片扩展名和附件扩展名是两个独立字段，别只改一个。
• 开过云存储的站点，用「切回本地」这个动作来二分定位问题在哪一层。