Composer create-project 跑不动的主因是PHP环境不达标：需PHP≥7.4且启用mbstring、openssl、pdo_mysql、curl、json扩展；init须用普通用户执行；Nginx root必须指向frontend/web；错误优先查runtime/logs/app.log。
composer create-project 跑不动？先确认 PHP 和扩展
Yii2 高级模板依赖 composer 安装，但很多 Linux 服务器上直接执行 composer create-project --prefer-dist yiisoft/yii2-app-advanced 会卡住或报错，根本原因不是 Yii2 本身，而是环境没达标。
- PHP 版本必须 ≥ 7.4（推荐 8.0+），运行
php -v确认；Yii2 2.0.48+ 已不支持 PHP 7.2 - 必需扩展：
mbstring、openssl、pdo_mysql（或对应数据库驱动）、curl、json—— 缺一个，composer install就会在 autoload 阶段失败 - 常见错误现象：
Class 'yii\BaseYii' not found或require(): Failed opening required 'vendor/autoload.php'，基本都是扩展缺失或vendor/没生成全
高级模板 init 命令报 Permission denied？别用 root 直接跑
init 是高级模板初始化关键步骤，但它会修改大量文件权限和内容。在生产服务器上，用 root 用户执行会导致后续 Web 服务（如 Nginx + PHP-FPM）因权限过高被拒绝读取配置，反而更难调。
- 用普通用户（比如
www-data或你创建的部署用户）执行./init，并选择0（Development）或1（Production）环境 - 如果提示
Permission denied，检查当前目录及environments/下文件是否可写：ls -l environments/；常见原因是上传压缩包后未chown所属用户 - 不要跳过
init直接复制environments/production过去——它不只是复制，还会执行copy+chmod+replace，漏一步，index.php就加载不到正确配置
Web 服务器怎么配？Nginx 的 root 和 index 必须指向 frontend/web
高级模板有 frontend 和 backend 两个入口，但默认安装后只暴露 frontend/web。很多人把 Nginx 的 root 设成项目根目录，结果直接看到一堆 PHP 文件被下载或 500 错误。
- Nginx 配置里，
root必须是/path/to/project/frontend/web（不是项目根目录，也不是frontend） -
index必须设为index.php，且要启用try_files $uri $uri/ /index.php?$args;，否则路由失效 - PHP-FPM socket 路径要核对：Ubuntu 常用
unix:/run/php/php8.1-fpm.sock，CentOS 可能是127.0.0.1:9000；错一个字符，Nginx 日志里就只有connect() failed (111: Connection refused)
第一次访问白屏或 500？立刻看 runtime/logs/app.log
Yii2 把绝大多数运行时错误都记在 runtime/logs/app.log，而不是 PHP 错误日志或 Nginx error.log。线上环境默认关闭 display_errors，所以浏览器只看到空白或通用 500，实际原因藏在日志里。
- 确保
runtime/和web/assets/目录可写（chown -R www-data:www-data runtime web/assets） - 典型错误：
Failed to write file "xxx" to directory "/path/runtime/cache"→ 缓存目录不可写；SQLSTATE[HY000] [2002] Connection refused→ 数据库服务没起来或配置错端口 - 开发阶段可临时在
frontend/web/index.php顶部加ini_set('display_errors', '1');，但上线前必须删掉——这不是调试手段，只是快速定位
路径权限、日志位置、入口目录层级，这三个点错一个，部署就停在“看起来装好了但打不开”的状态。没人会告诉你 runtime/ 不可写会导致整个应用静默失败，得自己翻 log。
