Yii文件上传核心是UploadedFile::getInstance()（单文件）和getInstances()（多文件），必须设enctype="multipart/form-data"，规则需配置extensions、maxFiles等，saveAs前须确保目录存在且校验返回值。
Yii 框架里上传文件，核心就两条路：单文件走 UploadedFile::getInstance()，多文件走 UploadedFile::getInstances()。别被插件或扩展绕晕，底层逻辑就这俩函数撑着。
单文件上传必须设 enctype="multipart/form-data"
表单没这个属性，$_FILES 就是空的，UploadedFile::getInstance() 必然返回 null。常见错误是只写了 method="post" 却漏掉 enctype。
- 视图中用
ActiveForm时，一定要加['options' => ['enctype' => 'multipart/form-data']] - 手写
标签时，必须显式写全enctype="multipart/form-data" - AJAX 上传（比如用
fetch或FormData）时，不能靠contentType: false就以为够了——FormData本身已处理边界，但服务端仍要按$_FILES接收，不设 enctype 不影响 JS 端，但后端 Yii 会收不到
UploadedFile::getInstances() 处理多文件的坑
前端 是对的，但后端调用方式错一个字符就失败：
- 模型属性名必须和
name属性一致，比如name="avatar[]"，那就要用UploadedFile::getInstances($model, 'avatar')，不是'avatar[]' -
rules()里得明确允许多个：['file', 'maxFiles' => 10]，否则默认只认第一个 - 循环保存时别直接用
$file->saveAs(...)而不校验扩展名或大小——UploadedFile对象不自动做 mime 检查，得靠规则里的'extensions'和'checkExtensionByMimeType' => true
上传路径权限与目录创建要手动干预
Yii 不会自动创建深层目录，比如想存到 @webroot/uploads/2026/04/18/xxx.jpg，saveAs() 执行前得先确保路径存在：
- 用
FileHelper::createDirectory()创建目录，别依赖mkdir(..., 0777, true)——Windows 下权限参数无效，且 Yii 的FileHelper会自动处理跨平台路径分隔符 - 保存路径别硬编码绝对路径，优先用
Yii::getAlias('@webroot')或Yii::getAlias('@runtime')，避免部署时路径错乱 - 如果上传后访问 403 或 404，先确认 web 服务器（Nginx/Apache）是否允许访问该目录，尤其
@runtime默认不对外暴露
CSRF 验证冲突常发生在 CKEditor / Dropzone 类插件里
这类工具常发独立 POST 请求，不带 Yii 的 _csrf 参数，导致 400 错误。不能全局关 CSRF，得精准放行：
- 在对应控制器方法顶部加
public $enableCsrfValidation = false;（仅限该 action） - 更稳妥的做法是：在插件配置里把
_csrf值塞进请求头或 formData，比如 CKEditor 的filebrowserUploadUrl后拼上&_csrf=xxx - Dropzone 的
headers配置可传X-CSRF-Token，值从 meta 标签取：document.querySelector('meta[name="csrf-token"]').getAttribute('content')
真正容易被忽略的是：上传成功后，UploadedFile::getInstance() 返回的对象只在当前请求生命周期有效，它不持久化，也不代表文件已落盘——saveAs() 才是真正写磁盘的动作，而这个动作失败时不会抛异常，只返回 false，必须手动判断。
