Yii本地开发只需三步：装对PHP版本（建议8.0+）、配好Composer国内源、用create-project拉项目；PHP需启用PDO、mbstring、openssl等扩展；权限应设为ug+rwX而非777；db.php配置后须用php yii db验证连接。
Yii 框架本地开发环境不需要单独装“Yii 安装包”，它靠 Composer 管理，核心动作只有三步：装对 PHP 版本、配好 Composer、用 composer create-project 拉项目。其他所谓“安装 Yii”都是多余操作，容易卡在权限、路径或扩展缺失上。
PHP 版本和扩展必须提前验证
Yii2 要求 PHP ≥ 7.4（官方已停止支持 PHP 7.3），但实际开发中建议直接用 PHP 8.0+——不仅兼容性更好，php yii serve 的内置服务器在 PHP 8.0+ 上更稳定。别信“只要 php -v 显示版本就行”，必须确认以下扩展已启用：
-
PDO和对应数据库驱动（如pdo_mysql）——否则php yii migrate直接报错Class 'yii\db\Connection' not found或连接失败 -
mbstring—— 缺失会导致 URL 解析异常、中文路由 404 -
openssl—— 影响 Composer 下载依赖，尤其在国内网络环境下容易静默失败 -
json、filter、session这些基础扩展也得在php -m输出里看到
Windows 用户注意：php.ini 文件可能有两份（CLI 和 Apache 各一份），务必检查你运行 php 命令时实际加载的是哪一份（php --ini 可查）。
Composer 配置国内源并验证可用性
默认 Packagist 源在国内极慢，且常因 TLS 握手失败导致 composer create-project 卡在 “Installing dependencies” 步骤。执行前先设阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
然后跑个最小验证：
composer create-project --no-install yiisoft/yii2-app-basic test-yii && echo "源可用"
如果这一步都失败，说明不是 Yii 的问题，是 Composer 环境没通——常见于公司代理、杀毒软件拦截、或 PHP 的 allow_url_fopen 被禁用（需在 php.ini 中设为 On）。
runtime 和 web/assets 权限不能靠 chmod 777 一劳永逸
Linux/macOS 下执行 chmod 777 runtime/ web/assets/ 是新手教程惯用写法，但它掩盖了真实权限模型问题。Web 服务器（如 Nginx）和 CLI 用户（你执行 php yii migrate 时的用户）往往不是同一个，硬设 777 在生产环境是安全风险，在 Docker 或 WSL 环境下还可能失效。
更稳妥的做法是：
- 查清 Web 服务运行用户（Nginx 默认是
www-data，Apache 常是apache或daemon） - 把该用户加进你当前 CLI 用户组，或反过来，让 CLI 用户能写入这些目录
- 用
chown -R $USER:www-data runtime/ web/assets/ && chmod -R ug+rwX runtime/ web/assets/替代 777
Windows 用户不用改权限，但要确保 IIS/Apache 服务账户对这两个文件夹有“修改”权限（右键 → 属性 → 安全 → 编辑），否则访问页面会提示 Unable to write to directory。
db.php 配置后必须手动测试连接
很多人改完 config/db.php 就直接跑 php yii migrate，结果报错 SQLSTATE[HY000] [1045] Access denied for user... 才回头查密码。其实 Yii 提供了轻量级连通性验证方式：
php yii db
这条命令不依赖迁移文件，只尝试连接数据库并输出版本号。如果失败，错误信息比 migrate 更干净直接。另外注意两点：
-
dsn中的host别写127.0.0.1当 localhost —— MySQL 对这两者权限处理不同，本地开发建议统一用localhost -
charset推荐显式写成utf8mb4（不是utf8），避免 emoji 或四字节 UTF-8 字符存不进去
最后提醒一句：php yii serve 启动的是 PHP 内置服务器，仅用于开发调试。它不解析 .htaccess、不支持虚拟主机配置，也扛不住并发请求——别把它当生产部署方案。
