ThinkPHP8前端文件上传需用原生<input type="file">，表单enctype设为multipart/form-data，name属性与后端request()->file('xxx')键名一致；后端需单独配置上传路由和控制器，文件应存至public/uploads并返回相对URL如/uploads/xxx.jpg。
首页模板里直接写 file input 标签就行
ThinkPHP8 没有内置「文件上传组件」这种前端控件，index.html 或 index.php 模板里要上传文件，就老老实实用原生 <input type="file">。框架只管后端接收和保存，前端完全由你控制。
常见错误是以为要引入某个 JS 组件或调用 Upload::widget() 之类的方法——没有这回事。TP8 不提供前端 UI 封装。
- 表单
enctype必须设为multipart/form-data，漏了就收不到文件 -
name属性值要和后端request()->file('xxx')里的键名一致，比如写name="avatar"，后端就得用request()->file('avatar') - 如果首页是通过
view::fetch('index')渲染的，确保模板路径正确（如view/index.html），否则 404 会让人误以为“组件没加载”
后端路由和控制器必须显式配好
首页本身不处理上传逻辑，你得额外定义一个接口地址，比如 /upload/avatar，并在 route/app.php 里注册：
Route::post('/upload/avatar', [UploadController::class, 'avatar']);
然后在 app/controller/UploadController.php 写处理方法。别指望首页控制器自动支持上传——IndexController 默认只响应 GET，POST 上传请求会被拒绝或 405。
立即学习“PHP免费学习笔记（深入）”；
- 若用
request()->file()拿不到文件，先dump($_FILES)看原始数据是否存在，排除表单提交问题 - TP8 默认禁用
$_FILES直接访问，必须走request()->file()，否则返回null - 上传失败时
$file->getError()返回的是字符串，不是数组，别用json_encode()包一层再返回，前端解析会出错
public 目录权限和磁盘配置决定能不能存进去
即使前端表单和后端路由都对了，move() 还是失败，八成卡在存储层。TP8 默认把文件往 runtime/storage 写，但这个目录通常不可 Web 访问，也不适合放用户上传内容。
更合理的做法是：让文件落地到 public/uploads，这样前端能直接用 /uploads/xxx.jpg 访问。
- 手动创建
public/uploads目录，并给 Web 进程（如 www-data）写权限：chmod 755 public/uploads - 不要依赖
Filesystem::disk('public')->putFile()，它默认写进public/storage，而你想要的是public/uploads——直接用$file->move('uploads')更直白 - 如果用了
move('uploads')却提示 “Directory not writable”，说明 PHP 进程没权限进public子目录，不是代码写错了
上传成功后返回路径别拼错
前端 JS 需要拿到真实可访问的 URL，后端别返回物理路径（如 /var/www/html/public/uploads/xxx.jpg），而要返回相对 URL（如 /uploads/xxx.jpg）。
TP8 的 $info->getSaveName() 只返回文件名，$info->getPathname() 是绝对路径，都不该直接传给前端。
- 推荐写法：
return json(['url' => '/uploads/' . $info->getSaveName()]); - 如果上传目录是按日期分的（如
uploads/2026/08/），记得把子路径也拼进 URL，不然前端请求 404 - 别在返回里加
http://或域名，容易跨域或 HTTPS 混合内容报错
public/uploads 目录的权限和 Nginx/Apache 的静态文件服务配置——代码全对，但 Web 服务器没把 /uploads/ 映射到该目录，结果图片永远 404。 
