macOS下安装Yii2并配置Nginx虚拟主机指南【说明】-php教程-PHP中文网

关键在于稳php、快composer、准nginx：需启用openssl/mbstring/pdo等扩展；配置国内镜像并装fxp/composer-asset-plugin；创建项目后运行./init选开发模式；nginx中fastcgi_pass端口须与php-fpm监听一致，否则502。

macos下安装yii2并配置nginx虚拟主机指南【说明】

在 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：配置加载、接口通信、资源获取都靠它们

二、配置 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），执行：

Icons8 Background Remover

一款由Icons8提供的在线AI背景移除工具，可自动分离图片主体与背景，方便快速制作透明图片和设计素材。

下载

基础版（适合入门）：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 块，例如：

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。