要让Yii2的UploadBehavior正确接管文件上传逻辑，必须明确配置class、属性映射、保存路径和验证规则这四个不可省略的要素，缺一不可；需确保类继承yii\base\Behavior且绑定对象为yii\base\Component子类，配置中'class'键不可少，attribute须对应真实UploadedFile类型属性，pathFormat与uploadRoot需配合使用真实文件系统路径，验证规则须在rules()中声明file验证器并设skipOnEmpty=>false，deleteOnRemove=true不保证事务一致性。
要让Yii2的UploadBehavior正确接管文件上传逻辑，必须明确配置class、属性映射、保存路径和验证规则这四个不可省略的要素，缺一不可。
确认UploadBehavior类路径与基础结构
UploadBehavior不是Yii2核心组件，需自行实现或引入第三方包（如yii2-upload-behavior），其类必须继承yii\base\Behavior且绑定对象必须是yii\base\Component子类（如ActiveRecord）。【未继承Component的模型无法使用任何Behavior】
在模型中声明行为时，配置数组开头必须包含'class'元素：
'uploadImage' => ['class' => 'common\behaviors\UploadBehavior']
绑定属性与文件字段映射
UploadBehavior需知道哪个模型属性对应上传的文件实例。常见错误是直接写'attribute' => 'imageFile'却不确保该属性真实存在且类型为yii\web\UploadedFile。
方法一：显式指定属性名
'attribute' => 'imageFile'
方法二：自动推导（仅当表单字段名与模型属性名一致时可用）
此时无需额外配置，但要求视图中使用$form->field($model, 'imageFile')->fileInput()，且模型中已声明public $imageFile;
注意：若模型属性名为avatar而表单字段名为Profile[avatar]，仍需显式配置'attribute' => 'avatar'，否则行为无法识别上传源。
设置上传后保存路径与文件名
路径配置决定文件最终落盘位置，必须同时提供相对路径模板和物理根目录。
第一步：定义路径格式字符串
'pathFormat' => '/uploads/{yyyy}/{mm}/{dd}/{rand:8}.{extension}'
第二步：指定绝对根路径（不能用别名如@webroot，必须是真实文件系统路径）
'uploadRoot' => Yii::getAlias('@webroot') → 错误！这是Web可访问路径，非文件系统路径
'uploadRoot' => dirname(dirname(__DIR__)) . '/web' → 正确，指向实际磁盘目录
第三步：组合生成完整路径
行为内部会将uploadRoot + pathFormat拼接，并自动创建缺失的子目录（如/uploads/2026/08/06/）
配置验证规则与安全限制
UploadBehavior自身不执行验证，它依赖模型层的rules()方法。必须在模型中为对应属性添加file验证器：
['imageFile', 'file', 'extensions' => 'jpg,png,gif', 'maxSize' => 2097152, 'mimeTypes' => 'image/jpeg,image/png,image/gif']
其中'mimeTypes'比'extensions'更可靠，因后者仅检查文件后缀，易被绕过。
若漏配'skipOnEmpty' => false，空文件提交时验证会跳过，导致后续save()失败且无提示。
启用删除联动与事务一致性
当模型记录被删除时，关联上传文件是否同步清除，由'deleteOnRemove'控制：
'deleteOnRemove' => true
但此操作非数据库事务一部分——文件删除成功而数据库回滚时，会产生孤立文件。若业务强依赖一致性，需手动在afterDelete()中调用$this->unlinkAll('uploadImage', true)并包裹try-catch。
'trueDelete' => true（来自多图上传插件）与此处无关，UploadBehavior不识别该键名。
