先确认php版本≥8.1、pdo_mysql已启用且vendor非空；再将数据库host从localhost改为127.0.0.1强制走tcp；接着验证autoload生效及web.php正确返回application实例；然后确保runtime/logs可写并生成日志；最后通过注释中间件逐级排查启动链路中断点。
本地开发好的Yii3项目部署到正式环境报错，不是代码写错了，而是环境不一致导致的配置、依赖、路径、权限或网络连接在服务器上失效——这类问题往往不报具体行号，只显示空白页、500错误或“Class not found”“Application not bootstrapped”等模糊提示。
第一步：确认基础运行环境是否达标
先别急着看日志，直接登录服务器执行三行命令：
php -v → 确认 PHP 版本 ≥ 8.1（Yii3 强制要求）；
php -m | grep pdo_mysql → 检查 pdo_mysql 扩展是否已启用；
ls -l vendor/ → 看 vendor 目录是否存在且非空，【若为空，说明 composer install 没跑成功或被跳过】。
很多报错本质是 PHP 解析器根本没加载到 Yii 入口文件，因为扩展缺失或 vendor 缺失，后续所有调试都白费。
第二步：检查数据库连接是否真正通达
Yii3 默认用 localhost 连 MySQL，但生产环境容器或云数据库常禁用 socket 连接，必须走 TCP。
打开 config/db.php，把 'dsn' => 'mysql:host=localhost;dbname=xxx' 改成 'dsn' => 'mysql:host=127.0.0.1;dbname=xxx' —— 【localhost 在 Linux 下默认走 Unix socket，而多数 Docker 或云 DB 不监听该 socket，改 127.0.0.1 强制走 TCP，90% 的 “Connection refused” 由此解决】。
接着手动测试连接：php -r "new PDO('mysql:host=127.0.0.1;dbname=xxx', 'user', 'pass'); echo 'OK';"，如果报错，说明凭证或网络不通，不是 Yii 配置问题。
第三步：验证自动加载与应用上下文是否就绪
常见报错如 “Class not found”、“Yii::$app is null”、“Application not bootstrapped”，核心原因是 Composer 自动加载未生效，或入口配置没返回完整 Application 实例。
方法一：检查 autoload 配置
运行 php composer.phar dump-autoload --optimize，确保 vendor/autoload.php 被正确 require；
方法二：直连入口验证
在 web/index.php 最顶部加一行：var_dump(class_exists(\Yiisoft\App\Application::class)); die();，如果输出 false，说明自动加载失败或命名空间路径错乱；
方法三：检查 config/web.php 返回值
确保 return 数组中 'class' 键明确指定为 \Yiisoft\App\Application::class，且 components 中的 'db'、'log' 等组件配置语法无 YAML/PHP 混淆（Yii3 只接受 PHP 数组，不支持 YAML 格式配置）。
第四步：定位日志缺失或权限问题
Yii3 默认把日志写入 runtime/logs/，但正式环境常因目录不可写导致静默失败——页面空白，其实是因为异常连日志都写不进去。
执行：mkdir -p runtime/logs && chmod 777 runtime && chmod 777 runtime/logs；
再访问一次页面，立刻查看 runtime/logs/app.log 是否有新内容；
如果没有生成任何日志文件，说明 web 服务器用户（如 www-data 或 nginx）对 runtime 目录无写权限，【chmod 777 是临时手段，上线后应改为 chown www-data:www-data runtime -R】。
第五步：逐级关闭中间件排查链路中断点
Yii3 启动流程含多个中间件（如 Router、ErrorHandler、AssetManager），某一个初始化失败就会阻断整个请求。
第一步：注释掉 config/web.php 中的 'middlewares' 数组全部内容，只保留最简 Application 初始化；
第二步：访问 /health 或任意路由，若返回正常，说明某个中间件配置异常；
第三步：逐个取消注释中间件，每次 reload 后测试，直到复现错误——例如 AssetManager 报错常因 @public basePath 不存在或不可读，Router 报错多因 URL 规则里用了本地开发才有的 host 匹配条件。
