必须用composer create-project安装yii2模板，如yii2-app-basic或yii2-app-advanced；手动require yiisoft/yii2仅得内核，缺失入口文件、配置结构和yii命令，必然导致白屏、404或class not found。
直接用 composer create-project 装对应模板，别手写 composer.json 或 require 单包——这是绝大多数失败的根源。
Yii 1.1 已彻底淘汰，不支持 Composer 安装
Yii 1.1 是 2010 年代的老版本，官方早在 2016 年就停止维护，且从未适配 Composer 的现代依赖管理机制。它没有 composer.json、不进 Packagist、也不提供应用模板。所谓“用 Composer 安装 Yii 1.1”本身就是伪命题。
- 如果你看到教程教你
composer require yiisoft/yii:1.1.*，那基本是过时文档或误传 - 实际只能通过官网下载 ZIP 包（如 yii-1.1.25.tgz），解压后手动配置 Web 服务器和入口文件
- PHP 7.4+ 环境下运行 Yii 1.1 会大量报错（如
mysql_*函数废弃、mb_ereg移除），不建议新项目使用
Yii 2.0 安装失败：90% 是环境或命令用错
Yii 2.0.x（最后稳定版 2.0.48）仍可安装，但必须严格按模板方式操作，且避开已知兼容陷阱。
-
必须用模板命令：
composer create-project --prefer-dist yiisoft/yii2-app-basic myproject 2.0.48—— 加版本号锁定，避免拉到非预期分支 -
禁用自动脚本：国内常卡在 GitHub API，加
--no-scripts参数，装完再进目录执行php init -
检查 PHP 版本与扩展：仅支持 PHP 7.4–8.1；
mbstring、openssl、pdo_mysql缺一不可，用php -m | grep -E "mbstring|openssl|pdo"快速验证 -
Asset 插件已弃用：Composer 2.x 不再需要
fxp/composer-asset-plugin，强行安装反而冲突；新版模板已内置 Bower/NPM 替代方案
Yii 3.0 不是“升级版”，而是全新框架，安装逻辑完全不同
Yii 3 是完全重写的现代化框架（基于 PSR 标准、依赖注入容器优先），不兼容 Yii 2 的任何代码，也不能用旧模板命令安装。
- 正确安装方式是：
composer create-project yiisoft/app myproject（官方推荐的最小应用模板） - 它不再区分 “basic/advanced”，也不带
web/index.php入口，而是用public/index.php+ PSR-15 中间件栈 - 要求 PHP ≥ 8.0，且强制启用
json、mbstring、curl、xml扩展；ext-opcache强烈建议开启 - 若执行
composer create-project yiisoft/yii2-app-basic却想装 Yii 3，结果一定是失败——因为包名、命名空间、结构全不同
通用排查：三步快速定位问题
不管哪个版本失败，先做这三件事：
- 运行
composer --version和php -v，确认 Composer ≥ 2.5、PHP 在对应版本范围内 - 执行
composer config -g repo.packagist，确保镜像源是https://packagist.proxy.fly.dev或阿里云，避免 GitHub 限流 - 删掉
vendor/和composer.lock，清空缓存：composer clear-cache，再重试带完整参数的 create-project 命令
