Windows 環境安裝 Yii 2 框架完整指南：Composer 方式與常見問題解決

前言：現代 Yii 專案請使用 Composer

本文針對 Windows 環境（Windows 10/11、Windows Server），說明 **Yii 2.0 透過 Composer 安裝** 的標準流程。舊版 `yiic` 命令已棄用，請勿參考過時教學。

前置需求

• PHP >= 7.4 (建議 8.1+)
• Composer 2.x
• 啟用擴展：`pdo_mysql`、`mbstring`、`intl`、`gd` 或 `imagick`、`openssl`
• 資料庫：MySQL 5.7+/8.0 或 PostgreSQL 13+

步驟一：安裝 Composer (若未安裝)

1. 下載 Composer-Setup.exe 並執行安裝
2. 安裝過程會自動加入系統 PATH，建議勾選「安裝開發模式」
3. 驗證：打開新終端機 (PowerShell/CMD/Git Bash)，執行 `composer --version`

步驟二：建立 Yii 專案

基本專案模板 (適合單一應用)

composer create-project --prefer-dist yiisoft/yii2-app-basic my-project

進階專案模板 (適合前後台分離、多模組)

composer create-project --prefer-dist yiisoft/yii2-app-advanced my-project

步驟三：初始化進階模板 (若選擇 advanced)

cd my-project
# Windows PowerShell
./init.bat
# 或 Git Bash / CMD
init.bat

選擇環境：

• 0 - Development (開發環境，除錯開啟、快取關閉)
• 1 - Production (生產環境，優化啟用、錯誤隱藏)

步驟四：資料庫配置

編輯對應環境的配置檔：

• Basic: `config/db.php`
• Advanced: `common/config/main-local.php`

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=yii2_db;charset=utf8mb4',
    'username' => 'root',
    'password' => 'your_password',
    'charset' => 'utf8mb4',
    'tablePrefix' => 'tbl_',
    'enableSchemaCache' => true, // 生產環境建議開啟
    'schemaCacheDuration' => 3600,
    'schemaCache' => 'cache',
];

步驟五：執行遷移建立資料表

# Basic
php yii migrate

# Advanced (在專案根目錄)
php yii migrate
# 或指定配置
php yii migrate --interactive=0

步驟六：啟動內建開發伺服器

# Basic
php yii serve --port=8080
# 訪問 https://localhost:8080

# Advanced (前台)
cd frontend
php yii serve --port=8080
# 訪問 https://localhost:8080

# Advanced (後台)
cd backend
php yii serve --port=8081
# 訪問 https://localhost:8081

步驟七：配置虛擬主機 (生產/開發推薦)

Apache (httpd-vhosts.conf)

    ServerName yii2-basic.local
    DocumentRoot "C:/www/my-project/web"
    
        AllowOverride All
        Require all granted
    
    # 開發環境關閉快取
    php_value opcache.enable 0



    ServerName yii2-frontend.local
    DocumentRoot "C:/www/my-project/frontend/web"
    
        AllowOverride All
        Require all granted
    



    ServerName yii2-backend.local
    DocumentRoot "C:/www/my-project/backend/web"
    
        AllowOverride All
        Require all granted
    

編輯 `C:\Windows\System32\drivers\etc\hosts`：

127.0.0.1 yii2-basic.local
127.0.0.1 yii2-frontend.local
127.0.0.1 yii2-backend.local

Nginx (nginx.conf)

server {
    listen 80;
    server_name yii2-basic.local;
    root C:/www/my-project/web;
    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000; # 或 php-cgi socket
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

常見問題與解決

開發效率工具推薦

• IDE：PhpStorm (內建 Yii 專用支援)、VS Code + PHP Intelephense + Yii2 Snippets
• 除錯：Xdebug 3 + PhpStorm/VS Code
• 程式碼風格：`composer require --dev yiisoft/yii2-coding-standards`，配合 PHP-CS-Fixer
• 測試：Codeception (Yii 內建支援)
• 資料庫工具：TablePlus、DBeaver、HeidiSQL

目錄結構速覽 (Advanced 模板)

my-project/
├── common/           # 共用代碼 (模型、組件、配置)
│   ├── config/       # 共用配置
│   ├── models/       # 共用模型 (User, LoginForm 等)
│   └── components/   # 共用組件
├── frontend/         # 前台應用
│   ├── controllers/
│   ├── views/
│   ├── web/          # 公開入口 (index.php, assets)
│   └── config/
├── backend/          # 後台應用
│   ├── controllers/
│   ├── views/
│   ├── web/
│   └── config/
├── console/          # 控制台命令 (遷移、定時任務)
├── environments/     # 環境配置模板
├── vendor/           # Composer 依賴
├── init.bat / init   # 初始化腳本
└── composer.json

結語

Windows 下安裝 Yii 2 核心在於 **Composer 依賴管理、正確的 PHP 環境變數、資料庫配置與虛擬主機設定** 。掌握標準流程，能避開 90% 的坑點，專注於業務開發。建議新專案直接使用 Advanced 模板，為未來擴展預留架構空間。