yii 2基础项目可一行命令快速启动：执行composer create-project --prefer-dist yiisoft/yii2-app-basic myapp，需确保php≥7.4、启用pdo/mbstring等扩展，配置正确后即可直接运行。
直接上手就能跑通，不需要魔改配置或额外编译——只要 PHP 版本 ≥ 7.4、composer 可用、PDO 和 mbstring 扩展已启用，composer create-project 一行命令就能拉起一个可运行的 Yii2 基础项目。
检查 PHP 环境是否达标
很多“安装失败”其实卡在第一步。别跳过验证：
- 执行
php -v，确认输出是PHP 7.4.x或更高（不支持 PHP 8.3+ 的某些 alpha 版本） - 执行
php -m | grep -E "pdo|mbstring|openssl|json"，缺任意一个，composer install会报错或yii serve启动即退出 - 虚拟主机用户务必进控制台查扩展列表，光看 PHP 版本没用；常见坑是
fileinfo缺失导致 asset 发布失败
用 composer 创建项目时选对模板
yiisoft/yii2-app-basic 和 yiisoft/yii2-app-advanced 不只是目录多几层的区别，结构差异直接影响后续开发路径：
- 新手或单应用项目，用
composer create-project yiisoft/yii2-app-basic myapp—— 路由、控制器、视图都在controllers/、views/下，调试直观 - 前后端分离或需多入口（如 admin / api / frontend），必须选
advanced模板，否则后期拆分成本远高于初始化多花的两分钟 - 避免手动复制 vendor 或改 autoload —— Composer 自动处理 autoloading，改了反而破坏 PSR-4 映射
数据库配置后必须验证连接，不能只靠 migrate 成功
config/db.php 写完不等于能用。常见错误不是语法错，而是权限或网络层问题：
-
dsn中的host别写127.0.0.1当本地测试没问题，但部署到 Docker 或云主机时，得换成容器名（如mysql）或内网 IP - 密码含特殊字符（如
@、/）必须 URL 编码，否则yii\db\Connection解析 DSN 失败，报错信息是SQLSTATE[HY000] [1045] Access denied，但真实原因是解析中断 - 运行
php yii migrate前，先执行php yii db（需装yiisoft/yii2-shell）或写个最小脚本调用(new \yii\db\Connection($config))->open()，比等 migrate 报错再排查快得多
权限和 runtime 目录写入失败是最隐蔽的启动障碍
页面空白、500 错误、日志无记录？八成是 runtime/ 或 web/assets/ 不可写，而 PHP 默认错误报告又关着：
- Linux/macOS：进项目根目录，执行
chmod 777 runtime/ web/assets/（仅开发环境；生产环境应设为755并用正确用户组） - Windows + XAMPP：右键文件夹 → 属性 → 安全 → 编辑 → 给
Everyone或Apache用户勾上“写入”权限 - advanced 模板要分别处理
frontend/runtime/、backend/runtime/，漏一个，对应子应用就 500 - 如果
runtime/下始终生成不了logs/app.log，说明写入彻底失败，先停掉所有服务，用ls -ld runtime看属主和权限位
真正卡住人的往往不是框架本身，而是 PHP 扩展缺失、DSN 特殊字符未编码、runtime 权限被 SELinux 或 Windows UAC 拦截——这些点不显眼，但一漏就白折腾半小时。
