Yii2上传失败显示500或空白，需启用调试模式、检查$_FILES是否为空、验证enctype属性、查看UploadedFile错误码、禁用CSRF验证、确保runtime和web/assets目录可写。
Yii2上传失败时页面只显示500错误或空白，根本看不到真实报错信息，导致排查像在黑箱里摸索——这通常不是代码写错了，而是环境配置、权限或CSRF验证卡在了上传流程最前端。
让真实错误浮出来
默认生产模式会静默吞掉异常，必须临时启用调试才能看到堆栈：
打开 web/index.php，确认第一行是：defined('YII_DEBUG') or define('YII_DEBUG', true);
同时确保同文件中 YII_ENV = 'dev' 已设置。若仍不显示错误，在 index.php 开头加两行强制输出：error_reporting(E_ALL); ini_set('display_errors', '1');
注意：这一步必须做，否则后续所有排查都建立在猜测上。
检查 $_FILES 是否为空
这是上传失败最常被忽略的第一关——表单没发出去，后端连文件影子都见不到。
在控制器 action 中开头加一句：var_dump($_FILES); die;，刷新页面看输出。
如果输出为空数组或 array(0) { }，说明请求根本没携带文件数据。此时要立刻检查视图表单是否漏了 enctype="multipart/form-data" ——ActiveForm 必须显式声明：<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]); ?>
缺这个属性，浏览器就当普通文本提交，$_FILES 永远为空，且不会报任何警告。
定位上传失败的具体原因
方法一：用 UploadedFile::getInstance 直接抓取
在控制器中写：$file = UploadedFile::getInstanceByName('myFile');（把 'myFile' 替换为你表单 input 的 name 属性值）
然后立刻检查：var_dump($file, $file ? $file->error : 'no file'); die;
方法二：查 PHP 原生错误码
若 $_FILES 不为空但 $_FILES['myFile']['error'] !== 0，对照 PHP 官方错误码判断：
1 → upload_max_filesize 超限；2 → 表单 MAX_FILE_SIZE 超限；3 → 文件只传了一半；4 → 根本没选文件；5 → 上传文件大小为 0。
特别注意：错误码 1 和 2 看似一样，但根源不同——前者改 php.ini 的 upload_max_filesize，后者改 HTML 表单里的 <input type="hidden" name="MAX_FILE_SIZE" value="2097152">。
绕过 CSRF 验证干扰
AJAX 上传或 API 接口上传失败，十有八九卡在 CSRF 验证上。
第一步：确认当前控制器是否继承自 Controller，如果是，直接在类顶部加：public $enableCsrfValidation = false;
第二步：如果控制器继承自 yii\rest\Controller 或其他基类，改用 beforeAction 方法：
① 在 action 方法前插入：public function beforeAction($action) { $this->enableCsrfValidation = false; return parent::beforeAction($action); }
② 注意：这个设置只对当前控制器生效，不能写在父类里影响全局。
第三步：REST 接口务必检查 request 组件配置，确保 'request' => ['enableCsrfValidation' => false] 已设——否则 POST 请求连框架初始化都过不去。
确认 runtime 和 web/assets 目录可写
Yii2 上传成功后常需生成 asset 或缓存文件，如果目录不可写，move_uploaded_file() 会静默失败。
Windows 下：右键 runtime 文件夹 → 属性 → 安全 → 编辑 → 添加 IIS_IUSRS 用户并勾选“修改”和“写入”权限。
Linux 下：执行 chmod -R 777 runtime web/assets（仅调试用），或更安全地：chown -R www-data:www-data runtime web/assets（www-data 替换为你 Web 服务器运行用户）。
关键点：Apache 或 Nginx 进程用户必须对这两个目录有写权限，否则上传文件能存，但后续操作（如生成缩略图、打包 asset）会崩在 500。
