Yii2 實戰安裝指南：歸檔包離線安裝 vs Composer 在線安裝，國內鏡像加速全流程

Yii2 實戰安裝指南：歸檔包離線安裝 vs Composer 在線安裝，國內鏡像加速全流程

Yii2 官方提供兩種安裝方式：**歸檔包解壓（高成功率、適合離線/受限網絡）** 與 **Composer 依賴管理（標準化、易更新、生產環境推薦）**。本文詳解兩種方式完整流程、常見失敗原因、國內鏡像配置、高級模板初始化、Nginx/Apache 虛擬主機配置。

方式一：歸檔包離線安裝（新手首選、成功率最高）

1. 下載高級模板歸檔包

• 官網：https://github.com/yiisoft/yii2-app-advanced/archive/refs/heads/master.zip
• 或国内鏡像：https://gitee.com/yiisoft/yii2-app-advanced/repository/archive/master.zip

2. 解壓並部署

unzip yii2-app-advanced-master.zip
mv yii2-app-advanced-master /var/www/yii2-advanced
cd /var/www/yii2-advanced

3. 初始化應用

# Linux/macOS
php init

# Windows
init.bat

# 交互選擇：
#   Which environment do you want the application to be initialized in?
#   [0] Development
#   [1] Production
# Your choice [0-1, or "q" to quit] 0
# Initialize the application under 'Development' environment? [yes|no] yes

4. 配置數據庫連接

# common/config/main-local.php
return [
    'components' => [
        'db' => [
            'class' => 'yii\db\Connection',
            'dsn' => 'mysql:host=localhost;dbname=yii2advanced',
            'username' => 'root',
            'password' => 'password',
            'charset' => 'utf8',
        ],
    ],
];

5. 執行遷移創建表

php yii migrate
# 輸入 yes 確認創建 user 表等

6. 配置 Web 服務器虛擬主機

# Nginx (frontend)
server {
    listen 80;
    server_name frontend.yii2.local;
    root /var/www/yii2-advanced/frontend/web;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

# Nginx (backend)
server {
    listen 80;
    server_name backend.yii2.local;
    root /var/www/yii2-advanced/backend/web;
    # ... 同前端配置
}

7. 訪問驗證

• 前台：https://frontend.yii2.local → 顯示「Congratulations!」
• 後台：https://backend.yii2.local → 登錄頁面

方式二：Composer 在線安裝（標準化、團隊協作、CI/CD 必備）

1. 安裝 Composer 並配置國內鏡像（關鍵！）

# 安裝 Composer
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# 配置阿里云/騰訊云/華為云全量鏡像（二選一）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
# 或
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
# 或
composer config -g repo.packagist composer https://repo.huaweicloud.com/repository/php/

2. 創建項目

composer create-project --prefer-dist yiisoft/yii2-app-advanced /var/www/yii2-advanced

3. 後續步驟同歸檔包方式（init、配置 DB、migrate、虛擬主機）

常見安裝失敗原因與解決

高級模板目錄結構解析

yii2-advanced/
├── common/           # 共用代碼：模型、組件、配置基類
│   ├── config/       # 共用配置 (main.php, main-local.php, params.php)
│   ├── models/       # 共用模型 (User, LoginForm, SignupForm)
│   └── components/   # 共用組件
├── frontend/         # 前台應用
│   ├── controllers/  # 控制器 (SiteController)
│   ├── views/        # 視圖
│   ├── web/          # Web 入口 (index.php, assets, favicon)
│   └── config/       # 前台專用配置
├── backend/          # 後台應用 (結構同 frontend)
├── console/          # 控制台應用 (命令、遷移、定時任務)
├── environments/     # 環境配置模板 (dev, prod)
├── vendor/           # Composer 依賴
├── init / init.bat   # 初始化腳本
└── yii / yii.bat     # 控制台入口

選型建議：學習/評估/離線環境 → 歸檔包（幾分鐘搞定，專注框架本身）；團隊項目/生產環境/持續集成 → Composer（依賴鎖定、版本管理、安全掃描、自動化部署）。**無論哪種方式，首要任務是配置國內 Composer 鏡像**，否則後續擴展包安裝將極其痛苦。