上传失败时应将$_FILES'xxx'错误码转为用户友好的中文提示，如“文件太大，请上传小于2MB的文件”，并严格区分接收阶段（error值）与移动阶段（move_uploaded_file返回值），同时前后端校验规则需统一、Web服务器配置须匹配PHP限制。
上传失败时直接显示 $_FILES 的 error 值会吓到用户
PHP 的 $_FILES['xxx']['error'] 返回的是整数错误码（如 1、2、4），直接 echo 出来毫无意义，用户看到 Upload error: 1 只会觉得系统崩了。真实问题往往只是 upload_max_filesize 超限或表单没加 enctype="multipart/form-data"，但错误码本身不带上下文。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 永远别把
$_FILES['xxx']['error']原样暴露给前端 - 用 switch 匹配错误码，转成一句人话提示，比如
1→ “文件太大，请上传小于 2MB 的文件” - 对
error === 0以外的情况，统一走友好提示分支，不记录敏感路径或配置值 - 开发期可额外写日志：
error_get_last()或error_log("Upload failed: " . print_r($_FILES, true), 3, "/tmp/upload.log")，但日志路径别暴露在响应里
move_uploaded_file() 失败不等于上传失败，别混为一谈
很多人以为 $_FILES['xxx']['error'] === 0 就万事大吉，结果 move_uploaded_file() 返回 false，又没处理，页面白屏或报错裸露。其实这是两个阶段：PHP 已接收临时文件（error === 0），但移动到目标目录时可能因权限、磁盘满、目录不存在而失败。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 必须检查
move_uploaded_file()的返回值，不能只看$_FILES['xxx']['error'] - 目标目录要提前用
is_writable()+is_dir()验证，失败时提示“服务器暂时无法保存文件，请稍后再试”，而非“Permission denied” - 避免用
die()或未捕获的异常中断流程；用 if/else 控制流向友好提示页或重定向回表单 - 临时文件路径（
$_FILES['xxx']['tmp_name']）不要打印，它可能含系统绝对路径，有信息泄露风险
前端校验和后端校验必须都做，但提示语气要一致
前端用 JS 检查文件大小、类型，能立刻反馈，体验好；但绕过浏览器太容易。如果后端校验失败后提示语是“非法文件类型”，而前端写的是“仅支持 JPG/PNG”，用户会困惑哪个为准。更糟的是，后端用 finfo_file() 判 mime 类型，结果提示“文件内容不符合要求”，用户根本不知道自己传错了什么。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 前后端允许的扩展名、大小上限、mime 类型列表必须严格同步，写死在配置里，避免一处改一处漏
- 后端校验失败时，提示尽量贴近前端文案，比如都用“请上传 JPG 或 PNG 格式的图片，且不超过 2MB”
- 不要依赖
$_FILES['xxx']['type']（浏览器可控），改用finfo_open()+finfo_file()做真实 mime 检查，但错误提示仍用扩展名口径，降低理解门槛 - 对非关键错误（如缩略图生成失败），可静默降级，主文件仍算上传成功
超时、断连、Nginx/Apache 代理层拦截导致无 error 码
用户点了上传，进度条走到一半卡住，刷新页面发现没反应——这往往不是 PHP 报错，而是 Nginx 的 client_max_body_size、fastcgi_read_timeout，或 Apache 的 LimitRequestBody 在起作用。此时 $_FILES 可能为空，$_POST 也空，error 字段甚至不存在，PHP 根本没收到完整请求。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 检查 Web 服务器配置是否与 PHP 的
upload_max_filesize和post_max_size匹配，常见坑是 Nginx 设了client_max_body_size 1M，PHP 却设了8M - 在入口脚本开头加判断：
if (empty($_FILES) && empty($_POST) && $_SERVER['CONTENT_LENGTH'] > 0) { /* 很可能是被代理层截断 */ } - 这种场景下，唯一稳妥的提示是“网络不稳定，请检查文件大小后重试”，别猜具体原因，也别提“Nginx”或“502”
- 大文件上传建议上分片或用专用服务（如 Uppy + tus），避开传统表单限制
真正难的不是捕获错误，而是判断哪一层出了问题、再把那层的术语翻译成用户能接受的表达。配置项、函数返回值、中间件行为之间存在多层映射，漏掉任意一环，友好提示就变成障眼法。
