先启用YII_DEBUG=true并强制显示错误，再查Web服务器日志、assets/runtime权限、cookieValidationKey配置及CSRF设置，逐项排除环境与配置问题。
Windows下安装Yii2后出现500错误，多数不是代码问题，而是环境配置或权限没到位。关键要让真实错误浮出来，再针对性解决。
打开调试模式看真实报错
默认生产模式会静默吞掉异常，只返回空白500页。必须临时启用调试：
- 打开 web/index.php，确认第一行是：
defined('YII_DEBUG') or define('YII_DEBUG', true); - 同时确保
YII_ENV = 'dev'（同文件中） - 若仍不显示堆栈，加两行强制输出：
error_reporting(E_ALL);ini_set('display_errors', '1');
检查Web服务器错误日志
IIS或Apache不会把PHP致命错误交给Yii处理，得直接查它们的日志：
- IIS：打开IIS管理器 → 选站点 → 右侧“错误页” → “编辑功能设置” → 勾选“详细错误” → Ctrl+F5刷新
-
Apache：查
logs/error.log（通常在Apache安装目录下） -
通用排查点：index.php权限是否为644（不能是664或777）、PHP模块是否加载（如php_mysqli.dll）、
display_errors = On是否在php.ini中启用
确认核心组件初始化是否失败
500常发生在应用启动阶段，比如数据库连不上、Redis扩展缺失、assets目录不可写：
- 检查 runtime/ 和 web/assets/ 目录是否对IIS用户（如IIS_IUSRS）或Apache服务账户（如SYSTEM）可写
- 运行
php -m | findstr "pdo_mysql redis"确认必需扩展已启用 - 注释掉 config/web.php 中的
'db'、'cache'等组件，逐个启用测试 - REST接口特别注意：
'request' => ['cookieValidationKey' => '随机32位以上字符串']必须配置，否则初始化就崩
绕过常见隐形陷阱
有些错误看似业务层，实则卡在框架底层：
-
CSRF验证干扰API：REST接口建议在request组件中设
'enableCsrfValidation' => false，避免POST请求因缺token被兜底成500 -
Nginx/Apache拦截错误页：IIS需禁用自定义错误页；Apache确认
php_flag display_errors on已生效；Nginx检查是否有fastcgi_intercept_errors on;并改为off -
Composer安装残留问题：若basic项目只有几百KB，大概率是GitHub token未配置导致asset下载中断，重新执行
composer install --prefer-dist并填入Personal Access Token
