composer create-project 是唯一靠谱的安装方式，手动 require 或下载 zip 会导致白屏、404、class 'yii' not found；必须使用官方模板（basic/advanced/api），装完立即执行 php init，并确保 web 服务器 root 指向 web/ 目录。
composer create-project 是唯一靠谱的安装方式，手动 require 或下载 ZIP 会直接导致白屏、404、Class 'Yii' not found——因为 Yii2 不是“装个库就能跑”的框架，它依赖模板提供的目录结构、入口文件、别名映射和初始化脚本。
为什么不能只 composer require yiisoft/yii2
单纯拉内核包，不带 web/index.php、不生成 config/web.php、不注册 @app 别名，连 Application 实例都建不起来。
常见错误现象：Invalid Configuration – yii\base\InvalidConfigException、首页空白、yii 命令不存在。
使用场景：仅当你已有项目，只想验证某个组件（如 yii2-bootstrap5）是否兼容时才局部 require；新建项目必须走模板。
create-project 必须带对模板名和版本
官方只有三个受支持模板：yiisoft/yii2-app-basic（轻量）、yiisoft/yii2-app-advanced（前后端分离）、yiisoft/yii2-app-api（纯 API）。别写成 yii2 或 yii，会报 Could not find package。
PHP 8.0+ 用户注意：yii2-app-basic 最后稳定版是 2.0.48，它不支持 PHP 8.1+ 的部分新特性（如 strlen(null) 报 Deprecated），强行装可能卡在 mbstring 检测或反射警告上。
实操建议：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 装基础版且要稳定：
composer create-project --prefer-dist yiisoft/yii2-app-basic myproject 2.0.48 - 装高级版并跳过 Git 卡顿：
composer create-project --prefer-dist --no-scripts yiisoft/yii2-app-advanced advanced-project - 国内用户务必提前配镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
装完必须跑 php init，否则一定崩
create-project 只复制骨架，environments/ 目录、frontend/web/index.php、数据库配置占位符、调试模块开关……全靠 init 脚本生成。跳过这步，访问首页就是 Invalid Configuration。
常见错误现象：No input file specified、Class not found、debug 面板白屏。
实操建议：
- 进入项目根目录后立即执行：
php init - 开发环境选
0（Development），并加--overwrite=All清掉残留空配置 - Windows 用户若提示
'php' is not recognized，请确认 PHP 已加入系统 PATH，或用绝对路径调用
Web 服务器路径和入口文件最容易错
Yii2 入口不在项目根目录，而在 web/ 子目录里。Nginx/Apache 的 root 必须指向 /path/to/myproject/web，不是项目根目录；否则 require(__DIR__ . '/../vendor/autoload.php') 就会失败，报 Class 'Yii' not found。
本地快速验证命令：cd myproject/web && php -S localhost:8080 router.php —— 注意必须显式指定 router.php，否则 CSS/JS 全 404。
检查要点：
- 确认
myproject/web/index.php第一行是：require(__DIR__ . '/../vendor/autoload.php');（不是../../vendor，也不是/vendor） - 运行
ls ../vendor/autoload.php看文件是否存在 - 别手改
autoload.php，它是 Composer 自动生成的，改了也没用
mbstring、pdo）、Web 服务器路径设错、或漏掉 init。这些环节只要一个断链，整个应用就起不来。
