默认安装的 Yii 版本可能非最新，因 yii2-app-basic 的 latest stable tag 滞后于最新补丁；Yii 2 与 Yii 3 不兼容，需区分 yiisoft/yii2-app-basic（Yii 2）和 yiisoft/yii-project-template（Yii 3）；指定版本号如 2.0.48 更稳妥；务必使用 --prefer-dist；vendor/autoload.php 缺失、runtime/assets 权限不足、Apache 重写规则未生效是三大高频问题。
composer create-project 装出来的不是最新 Yii 版本？
默认执行 composer create-project --prefer-dist yiisoft/yii2-app-basic basic 会拉取 yii2-app-basic 的 latest stable tag，但这个 tag 可能滞后于 2.0.x 最新补丁（比如 2.0.48 已发布，但 tag 还卡在 2.0.47）。更麻烦的是，Yii 2 和 Yii 3 完全不兼容，yiisoft/yii2-app-basic 和 yiisoft/yii-project-template 是两套东西，搜错关键词就装错框架。
- 查清你要的版本：Yii 2 用
yiisoft/yii2-app-basic或yiisoft/yii2-app-advanced；Yii 3 用yiisoft/yii-project-template（注意没有 “2”） - 指定版本号更稳妥，例如装 Yii 2.0.48：
composer create-project --prefer-dist yiisoft/yii2-app-basic basic 2.0.48 - 装 Yii 3（PHP 8.0+）：
composer create-project --prefer-dist yiisoft/yii-project-template myapp，别漏掉--prefer-dist，否则可能拉源码而非预编译包，后续composer install更慢
vendor/autoload.php 找不到或报 Class not found
常见于手动移动项目目录、改名后没重跑 autoload，或 composer install 被跳过。Yii 启动入口（如 web/index.php）第一行就是 require(__DIR__ . '/../vendor/autoload.php');，这个文件不存在或路径不对，直接 500。
- 确认当前目录下有
vendor/文件夹，且里面有autoload.php；没有就说明composer install没成功跑完 - 别用
cp -r复制整个项目去生产环境——vendor/是平台相关生成物，必须在目标机器上重新composer install --no-dev - 如果提示
Class 'Yii' not found，检查vendor/autoload.php是否真包含 Yii 的 PSR-4 映射（打开看有没有'Yii' => ...），极少数情况是 Composer 配置损坏，删掉vendor/和composer.lock重装
权限问题导致 runtime/ 或 assets/ 写入失败
Yii 运行时要往 runtime/（日志、缓存）和 assets/（资源包发布）写文件，Web 服务器用户（如 www-data、_www）没权限就会报 Failed to write file 或白屏无错误。
- Linux/macOS 下，进项目根目录执行：
chmod 775 runtime assets，再chown -R $USER:www-data runtime assets（把组设为 Web 用户组） - Windows WAMP/XAMPP 通常不用调权限，但若用 Docker，得确保容器内 Web 用户对这两个目录有写权，可在
Dockerfile加RUN chown -R www-data:www-data /app/runtime /app/assets - 别把
chmod 777当万能解——它会让 runtime 目录暴露可执行风险，尤其线上环境
Apache 伪静态规则没生效，访问 index.php 路由 404
Yii 默认用 PATH_INFO 模式，URL 如 /index.php/site/about，但启用美化 URL 后要靠 Web 服务器重写支持 /site/about。Apache 下没开 mod_rewrite 或没配 .htaccess，就会 404。
- 先确认 Apache 开了重写模块：
a2enmod rewrite（Debian/Ubuntu），然后重启apache2 - 确保项目
web/目录下有.htaccess（Yii 2 模板自带，Yii 3 默认不带，需手动加） - 关键点：Apache 虚拟主机配置里必须允许 .htaccess 覆盖，即
<directory> AllowOverride All </directory>，仅设AllowOverride None会导致规则被忽略
runtime/ 目录权限、autoload 加载链、重写规则生效条件——这三个地方出问题，比代码逻辑错更难定位，因为没报错或只报错半句。动手前先盯住它们。
