Yii2 進階應用初始化完整指南：環境配置、資料庫遷移與郵件服務設定

Yii2 進階應用初始化完整指南：環境配置、資料庫遷移與郵件服務設定

當 Yii2 進階版專案下載完成後，接下來的關鍵步驟是進行專案初始化，包含環境選擇、資料庫連線、資料表遷移以及郵件服務配置。本文將詳細記錄從零開始完成 Yii2 專案部署的完整流程，並針對團隊協作場景提供最佳實踐建議。

一、 專案初始化與環境切換

在 Windows 環境下，透過命令提示字元 (cmd) 進入 Yii2 專案根目錄，執行初始化指令：

init

系統將提示選擇環境：0 代表開發環境，1 代表生產環境。一般建議正式部署時選擇生產環境。值得注意的是，init 指令可重複執行以切換環境，但切換前必須確保 environments 目錄下已預先配置好對應環境的設定檔（如資料庫連線參數），否則切換過程可能覆蓋現有配置導致遺失關鍵設定。

二、 資料庫配置與團隊協作機制

初始化完成後，前台存取網址為 https://localhost/專案目錄/frontend/web/index.php，後台為 https://localhost/專案目錄/backend/web/index.php。首次存取通常會報資料庫連線錯誤，需依序完成：

1. 建立資料庫（建議使用 phpMyAdmin 等圖形化工具）。
2. 修改資料庫連線參數。配置檔分佈於三層目錄：common/config（前後台共用）、frontend/config、backend/config。優先級遞增，後者會覆蓋前者的同名設定。

每個目錄下又細分 main.php 與 main-local.php，這是為了解決團隊協作時的敏感資訊衝突：

• main.php 納入版本控制，存放通用設定。
• main-local.php 存放本機專屬的資料庫帳號、密碼等敏感資訊，不提交至 Git/SVN。

但這會導致新成員拉取程式碼時缺少 -local.php 而無法運行。解決方案正是利用 environments 目錄下的 dev（開發）與 prod（生產）環境模板。執行 init 時，系統會根據這些模板自動生成 *-local.php，新成員只需填入自己的資料庫憑證即可啟動專案。

三、 運行資料庫遷移建立用戶表

資料庫連線正常後，瀏覽器會提示找不到 user 資料表。Yii2 進階版已內建遷移檔案，位於 console/migrations/ 目錄下（檔名格式為 *_init.php）。在專案根目錄執行：

yii migrate

即可自動建立用戶表。migrate 是 Yii 強大的資料庫版本控制工具：團隊成員在本地新增資料表後，可用 yii migrate/create 產生遷移檔，提交版本庫；其他成員更新代碼後執行 yii migrate 即可同步資料庫結構，極大簡化了協作流程。

四、 郵件服務配置與常見錯誤排查

啟用「忘記密碼」功能需配置 SMTP 郵件發送。Yii2 整合了 SwiftMailer，配置位於 common/config/main-local.php：

'mailer' => [
    'class' => 'yii\swiftmailer\Mailer',
    'viewPath' => '@common/mail',
    'useFileTransport' => false, // 必須設為 false 才會真實發送郵件
    'transport' => [
        'class' => 'Swift_SmtpTransport',
        'host' => 'smtp.163.com',      // 以 163 郵箱為例
        'username' => '你的郵箱帳號',
        'password' => '你的郵箱授權碼', // 注意：這裡通常需填授權碼而非登入密碼
        'port' => '25',
        'encryption' => 'tls',
    ],
    'messageConfig' => [
        'charset' => 'UTF-8',
        'from' => ['你的郵箱帳號' => '系統機器人'],
    ],
],

常見錯誤： Expected response code 250 but got code "553", with message "553 Mail from must equal authorized user"。原因在於部分郵件伺服器（如網易）要求 From 欄位必須與 SMTP 登入帳號一致。Yii2 預設在 frontend/models/PasswordResetRequestForm.php 的 sendEmail 方法中使用 \Yii::$app->params['supportEmail']（預設為 admin@example.com）作為寄件人。

解決方案：

1. 修改 common/config/params.php 中的 supportEmail 為你的真實郵箱帳號。
2. 或啟用上方註解的 messageConfig 並移除 setFrom 那行代碼，讓統一配置生效。

團隊協作提示： 為了讓其他成員也能直接使用郵件功能，應在 environments/dev/common/main-local.php 中放入郵件配置模板，將 host、username、password、port 留空，由各成員自行填寫。

總結

完成上述四大步驟，Yii2 進階版專案即具備基本運行條件。後續可進一步整合美觀的後台模板、自定義 Gii 代碼生成模板等進階功能。掌握 init 環境機制、main-local.php 隔離策略與 migrate 遷移流程，是高效進行 Yii2 團隊開發的基石。