关键在于稳PHP、快Composer、准Nginx：需启用openssl/mbstring/pdo等扩展；配置国内镜像并装fxp/composer-asset-plugin；创建项目后运行./init选开发模式；Nginx中fastcgi_pass端口须与PHP-FPM监听一致，否则502。
在 macOS 上装好 Yii2 并配好 Nginx 虚拟主机，关键不是堆命令，而是理清三件事：PHP 环境得稳、Composer 下载得快、Nginx 配置得准。跳过 GitHub 认证卡顿、asset 插件报错、502 Bad Gateway 这几类高频问题，整个流程其实很顺。
一、确认 PHP 和必要扩展已启用
Yii2 要求 PHP ≥ 7.1（推荐 7.4–8.2），且以下扩展必须开启：
- openssl：保障 HTTPS 请求和 Composer 下载
- mbstring：处理中文等多字节字符，框架底层强依赖
- pdo 和 pdo_mysql：数据库连接基础（哪怕暂不连库也得有）
- curl、json、xml：配置加载、接口通信、资源获取都靠它们
终端执行：
php -v 查版本；
php -m | grep -E "openssl|mbstring|pdo|curl|json|xml" 检查是否全在列表里。
若缺失，打开 php.ini（可用 php --ini 定位路径），取消对应 extension=xxx 行前的分号，保存后重启终端或重载 PHP 服务。
二、配置 Composer（含国内镜像与 asset 插件）
macOS 安装 Composer 推荐用官方脚本：
- 运行：curl -sS https://getcomposer.org/installer | php
- 移至全局：sudo mv composer.phar /usr/local/bin/composer
- 验证：composer --version
必须配置国内镜像（否则大概率卡在 GitHub API 限流）：
- 推荐新镜像：composer config -g repo.packagist composer https://packagist.proxy.fly.dev
- 升级到最新版：composer self-update
Yii2 依赖 Bower/NPM 包，需安装 bridge 插件。Composer 2.x（当前主流）请运行：
- composer global require fxp/composer-asset-plugin:^1.4.6
注意：该命令只执行一次，全局生效，无需每项目重复装。
三、创建 Yii2 项目并初始化
进入你打算放项目的目录（如 ~/Sites），执行：
- 基础版（适合入门）：composer create-project --prefer-dist yiisoft/yii2-app-basic basic
- 高级版（含 frontend/backend/console）：composer create-project --prefer-dist yiisoft/yii2-app-advanced advanced
安装中途若提示输入 GitHub Token，说明触发了 API 限流：
- 去 GitHub Settings → Developer settings → Personal access tokens → Generate new token
- 勾选 public_repo 即可，复制后粘贴回终端（输入时不可见，粘完直接回车）
项目生成后，进入目录运行：
- ./init → 选择 0（Development Environment）→ 确认执行
这一步会生成 common/config/main-local.php、frontend/web/index.php 等关键文件，并自动补全 cookieValidationKey，避免 400 错误。
四、配置 Nginx 虚拟主机（防 502 关键）
Nginx 必须搭配 PHP-FPM 才能跑 Yii2。先确认 PHP-FPM 已启用（Homebrew 安装 PHP 通常自带）：
- 启动：brew services start php
- 查看监听端口：lsof -i :9000（默认是 9000，部分版本用 socket 文件）
编辑 Nginx 配置（路径一般为 /usr/local/etc/nginx/nginx.conf 或 /opt/homebrew/etc/nginx/nginx.conf）：
- 在 http 块内添加一个 server 块，例如：
listen 8080;
server_name yii2.local;
root /Users/yourname/Sites/basic/web;
index index.php;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
⚠️ 注意：fastcgi_pass 的地址必须和 PHP-FPM 实际监听一致（不是 9090，也不是 unix socket 路径写错）。错配直接导致 502。
- 修改系统 hosts：sudo nano /etc/hosts，加一行：127.0.0.1 yii2.local
- 测试配置：nginx -t → 显示 syntax is ok 才继续
- 重载 Nginx：nginx -s reload（或 brew services restart nginx）
浏览器访问 http://yii2.local:8080，看到 Yii2 默认首页即成功。
