必须用 composer create-project 安装 Yii2，因手动 require 只拉核心包，缺失 web 入口、yii 命令和配置结构，导致 404 或 Class 'Yii' not found；基础版执行 composer create-project --prefer-dist yiisoft/yii2-app-basic basic，高级版执行 composer create-project --prefer-dist yiisoft/yii2-app-advanced advanced，并务必运行 php init 且确保 PHP 7.4–8.1 及 mbstring、openssl、pdo_mysql 扩展启用。
别用 composer require yiisoft/yii2 单独装核心包——它根本跑不起来，缺入口、缺命令、缺配置，白忙一场。
必须用 create-project 而不是 require
Yii2 不是普通 Composer 包，它是带完整骨架的应用模板。手动 require 只拉下核心代码，没 web/index.php、没 yii 命令、没 config/ 目录结构，访问直接 404 或 Class 'Yii' not found。
- 基础版（轻量 API / 快速验证）：运行
composer create-project --prefer-dist yiisoft/yii2-app-basic basic - 高级版（前后端分离 / 中大型项目）：运行
composer create-project --prefer-dist yiisoft/yii2-app-advanced advanced - 包名必须写全
yiisoft/yii2-app-basic，别漏yiisoft/或错写成yii2-basic - 加
--prefer-dist强制下载压缩包，比源码快且稳定
国内安装卡住？先换镜像 + 跳过脚本
卡在 yii2-auth-client、github.com 连接超时、或 failed to open stream，基本都是 Packagist 国内直连失败。硬等没用，得主动干预。
- 全局换阿里镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 安装时跳过 post-install 脚本（它们会调 GitHub API）：
composer create-project --no-scripts --prefer-dist yiisoft/yii2-app-basic basic - 装完进项目目录，再手动运行：
php init（选 Development 模式），它会生成 cookie key、软链环境配置等 - 别信“装完就能跑”，
--no-scripts是国内环境下的事实标准操作
PHP 版本和扩展不满足，create-project 会静默失败或报依赖冲突
报 Your requirements could not be resolved 或直接退出，大概率不是网络问题，而是环境不达标。
- Yii2.1+ 要求 PHP ≥ 7.1，但实际推荐用 PHP 7.4–8.1；PHP 8.2 已出现兼容性警告，暂不建议
- 必须启用的扩展：
mbstring、openssl、pdo_mysql（哪怕你暂时不用 MySQL，框架初始化也检查） - 验证方式：
php -v看版本，php -m | grep -E 'mbstring|openssl|pdo'看扩展 - Linux/macOS 装完要给
vendor/bin/yii加执行权限：chmod +x vendor/bin/yii
高级版装完不能直接访问？init 和 DOCUMENT_ROOT 是两个死穴
高级版不是把整个项目根目录扔给 Web 服务器就完事。没走对这两步，frontend/web/index.php 会报 InvalidParamException 或空白页。
- 必须进
advanced/目录后运行php init，否则environments/下的配置不会生成，也不会软链到frontend/web/等位置 - Web 服务器的
DOCUMENT_ROOT必须指向frontend/web/（前台）或backend/web/（后台），不是项目根目录 - Windows 用户注意：
yii命令实际是yii.bat，别 chmod，直接用php yii serve启动内置服务器更省事 - 本地开发建议统一用
php yii serve（PHP 7.4+ 内置），避开重写规则和.htaccess配置陷阱
最常被跳过的其实是 php init 和扩展检查——前者让高级版直接瘫痪，后者让基础版在第一步就卡死，但错误信息往往不提示具体原因。
