必须串联model验证、控制器接收、文件存储路径生成、目录自动创建、图片重命名、缩略图处理及前端表单配置六环节；model层需定义avatar字段并配置image验证规则，extensions须小写逗号分隔，同时补充attributelabels；视图层表单需设enctype="multipart/form-data"并支持预览。
要在Yii2项目中让用户能上传头像并正确保存到服务器、更新数据库、显示在页面上，必须串联model验证、控制器接收、文件存储路径生成、目录自动创建、图片重命名、缩略图处理（可选）以及前端表单配置这六个环节——漏掉任意一环，头像就可能上传失败、覆盖旧图、无法访问或被恶意文件攻破。
Model层：定义头像字段与验证规则
打开用户模型文件（如User.php），在rules()方法里添加头像上传专用验证规则：
先引入必要类：use yii\web\UploadedFile;
在rules()数组中加入这一条：[['avatar'], 'image', 'extensions' => 'jpg, jpeg, png, gif', 'maxSize' => 2097152, 'minWidth' => 100, 'minHeight' => 100, 'tooBig' => '头像不能超过2MB', 'wrongExtension' => '仅支持JPG、PNG、GIF格式']。
【extensions必须小写且用英文逗号分隔，大小写混写或中文顿号会导致验证永远不通过】
同时在attributes()或attributeLabels()里补充：'avatar' => '头像'，否则表单label会显示为“Avatar”。
视图层：构建安全可交互的上传表单
在用户编辑页（如views/user/update.php）中，使用ActiveForm生成带文件上传能力的表单：
确保表单开启multipart/form-data编码：$form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]);
插入头像字段：= $form->field($model, 'avatar')->fileInput(['accept' => 'image/*']) ?>。
如果希望保留原头像预览，加一段逻辑判断：<?php if ($model->avatar && file_exists(Yii::getAlias('@uploadPath') . '/' . $model->avatar)): ?><img src="https://img.php.cn/?x-oss-process=image/resize,p_40" alt="从零搭建：Yii2用户头像上传完整流程">avatar ?>" width="80" style="max-width:90%" alt="当前头像"><?php endif; ?>。
这一步不做预览，用户就无法确认自己是否真传了新图——尤其在移动端，点击“选择文件”后没反馈极易误操作。
Controller层：接收、保存、重命名与路径管理
在用户控制器（如UserController.php）的actionUpdate()中处理上传逻辑：
第一步：获取上传文件实例：$uploadedFile = UploadedFile::getInstance($model, 'avatar');
第二步：判断是否有新文件上传：if ($uploadedFile) {
第三步：生成唯一文件名，避免覆盖和猜解：$fileName = md5(uniqid(microtime(true), true)) . '.' . $uploadedFile->extension;
第四步：构造完整保存路径：$uploadPath = Yii::getAlias('@uploadPath') . '/avatars/' . date('Y/m/') . $fileName;
第五步：递归创建目录（关键！否则saveAs会因路径不存在而静默失败）：FileHelper::createDirectory(dirname($uploadPath));
第六步：保存文件：$uploadedFile->saveAs($uploadPath);
第七步：把相对路径存入模型：$model->avatar = 'avatars/' . date('Y/m/') . $fileName;
第八步：调用$model->save()持久化到数据库。
注意：若未调用FileHelper::createDirectory()，Linux服务器下直接报错“failed to open stream: No such file or directory”，Windows可能侥幸成功但路径不一致。
配置层：声明上传根路径别名与权限
在config/web.php的aliases数组中添加：
'@uploadPath' => dirname(__DIR__) . '/web/uploads',
'@uploadUrl' => '@web/uploads',
然后在服务器上执行：chmod -R 755 web/uploads（Linux/macOS）或确保IIS/Apache对web/uploads目录有写入权限（Windows）。
【web/uploads目录必须存在且可写，否则所有上传都会卡在saveAs()返回false】
这一步跳过，后续所有上传都只会返回空字符串或null，日志里也不报错，排查起来极耗时间。
增强层：添加头像裁剪与缩略图支持（可选）
若需头像裁剪，推荐集成yii2-imagine扩展：
方法一：用Composer安装：composer require yiisoft/yii2-imagine
方法二：在Controller保存后追加缩略图生成逻辑：
use yii\imagine\Image;
Image::thumbnail($uploadPath, 200, 200)->save(str_replace('.jpg', '_thumb.jpg', $uploadPath));
注意：此操作必须在$uploadedFile->saveAs()之后执行，否则源文件还不存在。
