跨平台安装 Yii2 的核心是统一环境要求并适配系统特性，而非重写流程；只要 PHP ≥ 7.4 且启用 mbstring、openssl、pdo_mysql、curl、json 扩展，Windows、macOS、Linux 安装逻辑完全一致，仅路径、权限和 Web 服务器配置存在细节差异。
跨平台安装 Yii2 的核心在于统一环境要求、适配不同系统特性，而非重写流程。只要 PHP 版本 ≥ 7.4（推荐 8.0+），并启用 mbstring、openssl、pdo_mysql、curl、json 这五个扩展，Windows、macOS、Linux 三者安装逻辑完全一致，差异仅体现在路径写法、权限控制和 Web 服务器配置细节上。
环境准备：三平台共性检查项
无论用哪套系统，都必须先确认以下几点：
- 运行
php -v，确保输出版本号 ≥ 7.4；低于该版本会直接导致composer install失败或运行时报Class 'yii\BaseYii' not found - 执行
php -m | grep -E "mbstring|openssl|pdo|curl|json"（Linux/macOS）或在 Windows 的phpinfo()页面中逐项核对，缺一不可 - 安装 Composer 并更新至最新版：
composer self-update；若首次使用，需额外执行composer global require "fxp/composer-asset-plugin:~1.4"（Yii 2.0.x 旧项目仍依赖此插件） - 禁用 SELinux（仅 Linux 生产环境）或关闭 Windows Defender 实时防护（尤其解压/写入
runtime/目录时易被拦截）
项目获取：两种可靠方式任选
不推荐下载 ZIP 包手动解压——密钥未自动生成、权限易错、后续升级困难。优先使用 Composer 创建：
-
基础模板（适合学习或单应用）：
composer create-project --prefer-dist yiisoft/yii2-app-basic myapp -
高级模板（推荐生产/多模块项目）：
composer create-project --prefer-dist yiisoft/yii2-app-advanced yii2-proj - 如遇 GitHub API 限流卡住，按提示登录 GitHub 账号即可继续；也可提前设置 token：
composer config -g github-oauth.github.com your_token - 克隆镜像仓库（国内加速）：
git clone https://gitcode.com/gh_mirrors/yi/yii2-app-advanced，再进目录运行composer install
初始化与权限：关键但常被忽略的一步
高级模板必须运行 php init，它不只是复制文件，还会自动修正权限、替换占位符、生成正确环境配置。跳过将导致 500 错误或白屏。
- Windows：双击
init.bat或命令行运行php init，选0（开发）或1（生产） - macOS/Linux：确保当前用户对项目目录有读写权，运行
./init；若提示Permission denied，先chmod +x init - 生产环境务必用普通用户（如
www-data或自建部署用户）执行，严禁用 root 直接跑，否则 Nginx/PHP-FPM 因权限过高拒绝加载配置 - 验证是否成功：检查
environments/dev/frontend/web/index.php是否存在且开头含defined('YII_DEBUG') || define('YII_DEBUG', true);
Web 服务配置：指向正确的入口目录
Yii2 高级模板有 frontend 和 backend 两个独立应用，每个都有自己的 web/ 入口。Nginx/Apache 必须把 root 指向具体 web 子目录，而非项目根目录。
-
Nginx 示例（frontend）：
server { listen 80; server_name localhost; root /path/to/yii2-proj/frontend/web; index index.php; location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $request_filename; fastcgi_pass 127.0.0.1:9000; } } -
Apache（启用 mod_rewrite）：确保
frontend/web/.htaccess可读，AllowOverride All已开启 -
本地开发快速启动（无需配 Web 服务器）：
cd frontend/web && php -S localhost:8080 router.php，浏览器访问http://localhost:8080 - Windows 用户用 phpStudy/XAMPP：在虚拟主机配置中，
DocumentRoot必须设为.../frontend/web，不能是项目根目录
整个流程下来，从空环境到首页显示“Congratulations!”，通常不超过 15 分钟。真正耗时的环节往往是排查 PHP 扩展缺失或 Web 服务器 root 路径设错——这两点盯紧了，跨平台就真的只是换台电脑的事。
