yii文件上传失败主因是漏设enctype="multipart/form-data"或未处理uploadedfile::getinstance()返回null；表单须显式声明该属性，控制器须严格匹配字段名并校验saveas()返回值。
直接说结论：Yii 框架上传文件不难，但漏掉 enctype="multipart/form-data" 或没处理 UploadedFile::getInstance() 返回 null，90% 的上传失败都出在这两处。
form 必须加 enctype="multipart/form-data"
enctype="multipart/form-data"
Yii 的 ActiveForm 默认不会设置这个属性，而浏览器只有看到它才会把文件二进制数据打包进请求体。不加的话，$_FILES 为空，UploadedFile::getInstance() 必然返回 null，后续所有逻辑都跳过。
- 使用
ActiveForm::begin()时，必须显式传入：<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]); ?>
- 如果用原生
<form></form>，也得手动写：<form enctype="multipart/form-data"></form> - 常见错误：只改了 HTML 表单，但控制器里还按普通 POST 字段取值（比如
$model->imageFile = Yii::$app->request->post('imageFile')），这完全无效
UploadedFile::getInstance() 返回 null 怎么办
UploadedFile::getInstance() 返回 null 怎么办这个方法不是“自动绑定”，它从 $_FILES 中按字段名提取上传实例，字段名必须和 model 属性名、HTML input 的 name 完全一致，且大小写敏感。
- 正确示例（model 属性叫
imageFile）：$file = UploadedFile::getInstance($model, 'imageFile');
- 错误写法举例：
-
UploadedFile::getInstance($model, 'imagefile')（小写） -
UploadedFile::getInstance($model, 'ImageFile')（驼峰错位） -
UploadedFile::getInstance($model, 'file')（input name 是imageFile，但这里写成file）
-
- 调试建议：在控制器里加一行日志：
Yii::info($_FILES, __METHOD__); // 看看字段名和结构对不对
验证规则里 extensions 和 mimeTypes 别混用
extensions 和 mimeTypes 别混用'file' 验证器支持两种校验方式，但它们行为不同、开销不同：
extensions只检查后缀名（如.jpg），快但不安全，可被伪造mimeTypes会读取文件头判断真实 MIME 类型（如image/jpeg），更准但要读文件内容，大文件会慢-
推荐组合写法（兼顾安全与性能）：
['imageFile', 'file', 'extensions' => 'jpg, png, gif', 'mimeTypes' => 'image/jpeg, image/png, image/gif']
注意：多个值之间用英文逗号+空格分隔，不能写成数组；
mimeTypes值必须是标准 MIME 字符串，写image/jpg会失效
保存路径权限和目录不存在是静默失败点
$file->saveAs() 不抛异常，只返回布尔值。如果目标目录不存在或无写权限，它就默默返回 false，没有任何提示。
- 必须主动检查并创建目录：
$uploadDir = 'uploads/' . date('Y/m/d'); if (!is_dir($uploadDir)) { mkdir($uploadDir, 0755, true); } $filePath = $uploadDir . '/' . $file->baseName . '.' . $file->extension; if (!$file->saveAs($filePath)) { $model->addError('imageFile', '文件保存失败，请检查目录权限'); } - Linux 下注意：Web 进程用户（如
www-data）必须对uploads/目录有写权限；Windows 下一般没问题，但若部署在 IIS，要注意应用池身份 - 不要用绝对路径硬编码（如
D:/xampp/htdocs/myapp/uploads/），优先用Yii::getAlias('@webroot')拼接
真正的坑不在语法，而在上传成功后你没校验 saveAs() 的返回值，也没确认文件是否真的落盘了。
