必须强制开启PHP错误显示并启用YII_DEBUG=true，否则500错误被静默吞掉；需在web/index.php开头插入error_reporting(E_ALL); ini_set('display_errors', '1');并确认defined('YII_DEBUG') or define('YII_DEBUG', true);和YII_ENV='dev'已设置。
部署后只看到空白 500 页面，不是代码写错了，而是错误被 PHP 或 Yii 静默吞掉了。必须让真实报错浮出来，才能往下查。
强制在页面显示 PHP 错误
Yii 的 YII_DEBUG 开关只控制框架层异常展示，PHP 致命错误（如扩展缺失、语法错误）默认不输出。得绕过它直接开 PHP 的错误显示：
- 打开
web/index.php，在第一行defined('YII_DEBUG')前插入两行：
error_reporting(E_ALL);
ini_set('display_errors', '1');
- 确认
php.ini中display_errors = On且未被.htaccess或虚拟主机配置覆盖 - Linux 下若用 CLI 执行
php yii migrate报错，也要检查 CLI 模式的php.ini（路径通常不同于 Web 模式）
确保 YII_DEBUG 和 YII_ENV 生效
即使加了 display_errors，如果 YII_DEBUG 是 false，Yii 仍会屏蔽堆栈跟踪。必须同时满足：
-
web/index.php中这两行必须存在且为true和'dev'：
defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');
- 不要在
config/web.php或其他地方重定义它们——这些常量只能在入口脚本中首次定义才有效 - 部署脚本若自动替换环境变量（如用
sed改YII_ENV），要确认没把true写成字符串'true'，否则判断失效
查 Web 服务器原生日志，别只盯浏览器
很多 500 错误根本没进 Yii，比如 require vendor/autoload.php 失败、open_basedir 限制、opcache 编译失败——这些 PHP 解析期错误只会记在 Web 服务器日志里：
- Apache：查
logs/error.log（路径取决于安装方式，宝塔在/www/wwwlogs/your-site.error.log） - Nginx：查
logs/error.log，重点看FastCGI sent in stderr后的内容 - IIS：在 IIS 管理器 → 站点 → “错误页” → 关闭“详细错误”开关后，再查 Windows 事件查看器 → 应用程序日志
- 若日志里出现
Failed opening required 'vendor/autoload.php'，说明__DIR__ . '/../vendor/autoload.php'路径算错了，常见于 Nginx 的$realpath_root配错
自动化部署时绕过“看不见的坑”
CI/CD 脚本里容易漏掉权限和上下文差异：
- 运行
composer install的用户和 Web 进程用户不同（如rootvswww-data），导致runtime/和web/assets/所有者不对——部署后立刻补：chown -R www-data:www-data runtime web/assets - Docker 容器内执行
php yii migrate时，display_errors默认关闭，必须显式传参：php -d display_errors=1 yii migrate - 某些 PaaS 平台（如阿里云函数计算）禁用
display_errors且无法修改，此时唯一办法是把错误写进runtime/logs/app.log并挂载日志卷
真正卡住人的往往不是报错内容本身，而是错误根本没出来——先让错误可见，剩下的才是框架或业务逻辑的事。
