Yii2/3部署白屏主因是Web根目录未设为web/或public/子目录、错误被静默屏蔽、vendor等关键文件缺失；须将DocumentRoot精确指向web/、在index.php开头启用error_reporting和YII_DEBUG、确保runtime与assets可写且vendor完整。
Yii2.0（或Yii3）部署后白屏，不是代码写错了，而是环境没搭对——最常见原因就三个：Web根目录设错、错误被静默吞掉、关键文件缺失。解决思路很直接：先让错误显示出来，再按提示逐项修复。
必须把Web服务器根目录指向 web/ 子目录
这是90%白屏的根源。Yii设计上只允许 web/ 下的文件被公网访问，config/、runtime/、vendor/ 等目录绝不能暴露。如果根目录设在项目主目录（比如 /var/www/html/myapp），就会出现：
- 访问时空白，无任何提示
- 日志里报
require(): Failed opening required '.../requirements.php' - 甚至可能泄露
config/main-local.php导致数据库密码外泄
正确做法：
- Apache/Nginx 的 DocumentRoot 或根目录路径，必须精确到
web/（例如/var/www/html/myapp/web） - 宝塔面板添加站点时，“根目录”填的是
/www/wwwroot/xxx/web，不是项目根 - XAMPP 或 phpStudy 中，不要把整个项目放
htdocs/myapp后访问/myapp/web/index.php，而应配置虚拟主机直指web/
强制显示PHP错误，别让它“装死”
默认生产模式会屏蔽所有错误，只返回空页。必须手动打开调试开关：
- 打开
web/index.php，确认前两行是：defined('YII_DEBUG') or define('YII_DEBUG', true);defined('YII_ENV') or define('YII_ENV', 'dev'); - 在
index.php最开头加两行（紧贴<?php之后）：error_reporting(E_ALL);ini_set('display_errors', '1'); - 检查
php.ini中display_errors = On是否生效，重启PHP服务
加上这些，白屏就会变成具体的报错页面，比如 “Class 'Yii' not found” 或 “vendor/autoload.php not found”，线索就明确了。
检查 vendor 和 autoload 是否完整
用 git clone 部署时，极易漏掉 vendor/ 目录——因为 Yii 官方模板自带 .gitignore，默认忽略 vendor/、runtime/、web/assets/ 等。
- 别用
composer require yiisoft/yii2单独装框架，这只会拉内核，不带应用结构；必须用：composer create-project --prefer-dist yiisoft/yii2-app-basic myapp - 若已用 git 部署，进服务器执行：
cd /path/to/project && composer install --no-dev - 确认
vendor/autoload.php文件真实存在，且权限为644（非777）
检查 runtime 和 assets 目录是否可写
Yii 运行时要往 runtime/ 写日志、缓存、锁文件；前端资源发布依赖 web/assets/。如果不可写，启动阶段就失败，但错误常被掩盖。
- 确保以下目录对 Web 服务器用户（如
www-data、nginx、IIS_IUSRS）可写：runtime/、web/assets/ - Linux 下常用命令：
chmod -R 755 runtime web/assetschown -R www-data:www-data runtime web/assets - 宝塔用户注意：重启 PHP 或一键部署可能重置权限，需重新设置
Yii3 原理一致，只是入口文件名可能变为 public/index.php，同样要确保 Web 根目录落在 public/ 下，并开启错误显示。核心逻辑没变：暴露最小必要路径 + 显式错误 + 可写运行时目录。
