Yii 框架核心配置總結：main.php 關鍵設置詳解 (defaultController、登錄、數據庫、錯誤、模塊)

Yii 1.1 核心配置文件 `protected/config/main.php` 是應用的大腦。本文總結最常用、最關鍵的五大配置板塊，附代碼示例與說明。

1. 修改默認控制器

<?php
return [
    // ...
    'defaultController' => 'main', // 默認訪問 MainController
    // ...
];

• 默認值為 site (即 SiteController)。
• 修改後，訪問網站根路徑 `/` 將路由到 MainController::actionIndex()。
• 需確保 MainController 存在且有 actionIndex。

2. 修改默認登錄 Action

<?php
return [
    // ...
    'components' => [
        'user' => [
            'allowAutoLogin' => true,           // 支持「記住我」自動登錄
            'loginUrl' => ['main/login'],       // 未登錄訪問受限頁面時跳轉的路由
        ],
        // ...
    ],
];

• 默認 site/login。
• 數組格式 ['controller/action'] 自動生成 URL。
• 模塊中也可單獨覆蓋此配置。

3. 數據庫連接配置 (db 組件)

<?php
return [
    // ...
    'components' => [
        'db' => [
            'connectionString' => 'mysql:host=localhost;dbname=my_db',
            'username' => 'root',
            'password' => 'secret',
            'charset' => 'utf8',
            'tablePrefix' => 'tbl_',      // 表前綴，AR 自動拼接
            'emulatePrepare' => true,     // 模擬預處理，兼容舊版驅動
            'enableProfiling' => true,    // 調試模式下啟用 SQL 分析
            'enableParamLogging' => true, // 記錄參數綁定
        ],
        // ...
    ],
];

• 之後全局可用 Yii::app()->db 獲取 CDbConnection 實例。
• 支持從獨立文件引入：'db' => require('db.php')。

4. 默認錯誤處理 Action

<?php
return [
    // ...
    'components' => [
        'errorHandler' => [
            'errorAction' => 'main/error', // 發生錯誤時執行 MainController::actionError()
        ],
        // ...
    ],
];

• 需實現 actionError()，框架會自動傳遞錯誤信息。
• 生產環境建議關閉 YII_DEBUG，友好展示錯誤頁面。

5. 模塊註冊與訪問

<?php
return [
    // ...
    'modules' => [
        'admin',        // 簡寫：模塊 ID = 類名 (AdminModule)
        'forum' => [    // 完整配置：支持模塊級參數
            'class' => 'application.modules.forum.ForumModule',
            'defaultController' => 'post',
        ],
    ],
];

• 註冊後可通過 /admin、/forum 訪問模塊。
• 模塊內部有獨立的 MVC 結構、配置、組件。

完整 main.php 示例

<?php
return [
    'basePath' => dirname(__FILE__) . DIRECTORY_SEPARATOR . '..',
    'name' => 'My Yii Application',
    'defaultController' => 'main',
    'language' => 'zh_cn',
    'sourceLanguage' => 'en_us',
    'preload' => ['log'],
    'import' => [
        'application.models.*',
        'application.components.*',
    ],
    'modules' => [
        'gii' => [
            'class' => 'system.gii.GiiModule',
            'password' => '123456',
            'ipFilters' => ['127.0.0.1', '::1'],
        ],
        'admin',
    ],
    'components' => [
        'db' => [
            'connectionString' => 'mysql:host=localhost;dbname=test',
            'username' => 'root',
            'password' => '',
            'charset' => 'utf8',
            'tablePrefix' => 'tbl_',
        ],
        'urlManager' => [
            'urlFormat' => 'path',
            'showScriptName' => false,
            'rules' => [],
        ],
        'user' => [
            'allowAutoLogin' => true,
            'loginUrl' => ['main/login'],
        ],
        'errorHandler' => [
            'errorAction' => 'main/error',
        ],
        'log' => [
            'class' => 'CLogRouter',
            'routes' => [
                ['class' => 'CFileLogRoute', 'levels' => 'error, warning'],
                ['class' => 'CWebLogRoute', 'levels' => 'trace'],
            ],
        ],
    ],
    'params' => [
        'adminEmail' => 'admin@example.com',
    ],
];

配置加載順序與覆蓋機制

1. main.php (主配置)
2. main-local.php (本地覆蓋，Git 忽略，存放敏感信息)
3. 模塊配置 modules/xyz/config.php
4. 控制器 init() 中動態修改 Yii::app()->component->property

常見避坑指南

總結

Yii `main.php` 配置集中了應用的核心行為：**路由入口、用戶認證、數據持久化、錯誤處理、模塊化架構**。掌握這五大板塊，能快速搭建結構清晰、可維護的 Yii 應用。建議將敏感配置 (DB 密碼、API Key) 剝離到 `main-local.php` 並加入 `.gitignore`，實現配置與代碼分離。