必须生成唯一文件名并规划动态路径以保障安全与可维护性。具体包括：一、时间戳+随机数+原扩展名；二、uuid v4全局唯一标识；三、sha256哈希内容去重；路径按年月日三级分层，按业务模块设别名隔离，严禁路径注入，并需extensions与mimetypes双重校验及大小限制。
在Yii2项目中实现文件上传时，必须解决两个核心问题：防止同名覆盖导致数据丢失，以及避免路径混乱引发的安全与维护风险。直接使用原始文件名保存到固定目录，会因并发上传或恶意构造文件名而造成安全隐患或写入失败。
生成唯一文件名的三种方式
方法一：时间戳+随机数+原扩展名
在控制器或上传工具类中，用 date('YmdHis') . '_' . rand(10000, 99999) 拼接基础名，再拼上 $uploadedFile->extension。这种方式能保证每秒内万级并发也不重复，但不防重放攻击——同一毫秒多次上传仍可能撞号，【务必配合目录隔离使用】。
方法二：UUID v4 全局唯一标识
引入 ramsey/uuid 包后，调用 Uuid::uuid4()->toString() 生成32位小写字母+数字组合。它基于时间、随机数和MAC地址熵值生成，碰撞概率低于 10⁻³⁷，适合高可靠场景。这一步操作起来很简单，直接把 UUID 当文件名即可。
方法三：SHA256哈希原始内容
读取 $uploadedFile->tempName 文件流，计算 hash_file('sha256', $tempName)，截取前16位作文件名。相同内容永远得相同名，利于去重和CDN缓存，但首次上传需完整读取文件，大文件时延迟明显。
动态路径规划的分层逻辑
第一步：按年月日三级目录存储
路径格式设为 @uploads/{yyyy}/{mm}/{dd}/，对应 PHP 中 Yii::getAlias('@uploads') . '/' . date('Y/m/d')。这样单日上传超万张图也不会让一个目录膨胀到操作系统性能瓶颈（如ext4单目录建议不超过10万项）。
第二步：按业务模块划分根子目录
在 common/config/bootstrap.php 中定义多个别名：Yii::setAlias('uploads_avatar', dirname(dirname(__DIR__)) . '/uploads/avatar');Yii::setAlias('uploads_product', dirname(dirname(__DIR__)) . '/uploads/product');
不同模块调用各自别名，天然隔离权限与备份策略，也方便 Nginx 单独配置防盗链规则。
第三步：禁止用户可控路径注入
绝对不能将 $_POST['dir'] 或文件名中的 ../ 片段直接拼入路径。所有路径生成必须基于白名单规则或固定格式字符串，否则攻击者可上传 Webshell 到 ../../yii/web/index.php 覆盖入口文件。
安全落地的关键校验点
在模型的 rules() 中必须声明 'extensions' 和 'mimeTypes' 双重验证：[['file'], 'file', 'extensions' => 'jpg, png, gif', 'mimeTypes' => ['image/jpeg', 'image/png', 'image/gif']]。
仅靠扩展名可被伪造，仅靠 MIME 类型易被绕过，两者叠加才能拦住大部分恶意文件。
上传前检查 $uploadedFile->size 是否超过预设阈值（如 5MB），并在 php.ini 中同步设置 upload_max_filesize 和 post_max_size。若 PHP 层未拦截，超大文件会先写满临时目录再报错，可能触发磁盘告警甚至服务中断。
保存文件时强制使用 $uploadedFile->saveAs($fullPath, true) 的第二个参数 true，确保目标路径不存在时自动创建父级目录。但注意：该操作依赖 mkdir() 权限，若 Web 进程无权在 @uploads 父目录下建目录，会静默失败——【首次部署必须手动创建 uploads 根目录并赋予 755 权限】。
