thinkphp文件上传需校验表单enctype、name匹配及服务器上传限制，检查$_files确认文件存在；move()前须确保目录存在且有写权限，用try-catch捕获异常；validate()校验真实mime类型和大小；返回结构化json数据。
ThinkPHP 文件上传接口不能只调用 move() 就完事，必须前置校验、明确路径权限、处理 null 和异常，否则上线后大概率 500 或静默失败。
表单提交后 request()->file('xxx') 返回 null 怎么办
这不是代码写错了，而是请求根本没把文件送进来。最常见三个原因：
- HTML 表单漏了
enctype="multipart/form-data"—— 没这个，$_FILES就是空数组，request()->file()必然 null - 前端
<input type="file" name="avatar">的name和后端request()->file('avatar')对不上 - PHP 或 Nginx 限制了上传大小：
upload_max_filesize、post_max_size、client_max_body_size三者中任意一个卡住，文件就被截断，$_FILES里error是UPLOAD_ERR_INI_SIZE，但 ThinkPHP 不主动暴露它
排查时先在控制器开头加一行：dump($_FILES); exit;，看原始数据是否存在、error 是否为 0。
move() 报错或返回 false，但没提示具体原因
$file->move() 失败时不会返回错误字符串，而是抛出异常（如目录不可写、磁盘满），或者返回 false（比如 validate 未通过但没 catch）。关键点：
- 目标目录（如
public/uploads/）必须真实存在，且 Web 进程有写权限（Linux 下常是www-data或nginx用户） - 别直接传
ROOT_PATH . 'public' . DS . 'uploads'给move()—— 如果DS是反斜杠（Windows）而路径拼出来带双反斜杠，某些版本会静默失败 - 务必用
try-catch包住move()，捕获\think\exception\FileException或通用Exception，否则 500 页面什么也看不到 -
move()成功后返回的是新think\File实例，不是布尔值；失败不返回false，而是抛异常 —— 别写if (!$info)这种判断
如何安全地限制类型、大小并生成可访问 URL
仅靠前端 accept 或后缀名白名单远远不够，真实 MIME 类型和文件头必须校验：
- 用
validate()做第一道过滤：$file->validate(['size' => 2097152, 'ext' => 'jpg,png,gif,jpeg', 'type' => 'image/jpeg,image/png,image/gif']) - 不要信任
$file->getOriginalExtension()，它来自客户端，可伪造；validate(['type' => ...])才读文件头做真实类型检测 - 保存路径建议固定为
public/uploads/这类 Web 可达目录，避免存到runtime/（无法直连访问） - 生成 URL 时，用
'/uploads/' . $info->getSaveName()，不是$info->getPathname()（那是服务器绝对路径） - 如果用
Filesystem::putFile()，注意它默认存到public/storage/，需先执行php think storage:link创建软链接才能通过/storage/访问
上传成功后怎么返回结构化数据
前后端联调时，前端需要明确知道“是否成功”“文件地址在哪”“错误信息是什么”，返回格式必须稳定：
- 成功时至少返回：
code: 0、url: '/uploads/20260425/abc123.png'、name: 'abc123.png' - 失败时统一用
code: 1，msg字段填具体错误，比如"文件大小超出 2MB 限制"或"不支持的文件类型"，别直接抛异常给前端 - 别用
halt()、dump()、echo等调试函数混在生产逻辑里，它们会破坏 JSON 格式 - 如果走 API 接口，响应头确保是
Content-Type: application/json，别被框架默认 HTML 模板覆盖
真正麻烦的从来不是“怎么把文件存进去”，而是“怎么让每一次失败都可定位、每一次成功都可访问、每一种边界情况都有兜底”。路径权限、MIME 校验、异常捕获、URL 拼接——这四点漏掉任一，上线后查日志能盯半小时。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
