Yii 框架 SQL 調試技巧全解析：從基礎日誌到專業工具

為什麼需要 SQL 調試

在 Yii 開發中，Active Record 和 Query Builder 封裝了底層 SQL，雖然提高了開發效率，但也帶來了「黑盒」問題：生成的 SQL 是否高效？是否存在 N+1 查詢？參數綁定是否正確？掌握調試技巧對性能優化與問題排查至關重要。

方案一：Yii 內置日誌系統（零依賴）

1. 開啟調試模式

在 index.php 入口文件中：

// 開啟調試模式（生產環境務必關閉）
defined('YII_DEBUG') or define('YII_DEBUG', true);
// 設置調用堆疊顯示層級（0-3，數值越大信息越詳盡）
defined('YII_TRACE_LEVEL') or define('YII_TRACE_LEVEL', 3);

2. 配置日誌路由

在 protected/config/main.php 中：

'log' => array(
    'class' => 'CLogRouter',
    'routes' => array(
        // 文件日誌：記錄錯誤與警告
        array(
            'class' => 'CFileLogRoute',
            'levels' => 'error, warning',
            'logFile' => 'application.log',
            'maxFileSize' => 1024 * 1024 * 5, // 5MB
            'maxLogFiles' => 10,
        ),
        // 網頁顯示：實時查看 SQL 執行情況
        array(
            'class' => 'CWebLogRoute',
            'levels' => 'trace',
            'categories' => 'system.db.*', // 只顯示數據庫相關
            'showInFireBug' => false,      // 不在 FireBug 顯示
        ),
        // 郵件告警：生產環境關鍵錯誤通知
        array(
            'class' => 'CEmailLogRoute',
            'levels' => 'error, warning',
            'emails' => 'admin@example.com',
        ),
    ),
),

3. 數據庫組件開啟分析

'db' => array(
    'connectionString' => 'mysql:host=localhost;dbname=test',
    'username' => 'root',
    'password' => '',
    'enableProfiling' => true,      // 啟用性能分析
    'enableParamLogging' => true,   // 記錄參數綁定詳情
    'schemaCachingDuration' => 3600, // 緩存表結構
),

方案二：Yii Debug Toolbar（可視化神器）

1. 安裝配置

下載 yii-debug-toolbar 解壓至 protected/extensions/，在配置中添加：

'log' => array(
    'class' => 'CLogRouter',
    'routes' => array(
        array(
            'class' => 'ext.yii-debug-toolbar.YiiDebugToolbarRoute',
            'ipFilters' => array('127.0.0.1', '192.168.*.*'), // 限制訪問 IP
            'toolbarTheme' => 'dark', // 暗色主題
        ),
    ),
),

2. 功能亮點

• SQL 時間線：按執行順序展示每條 SQL 耗時、參數、回溯堆疊
• EXPLAIN 分析：一鍵查看執行計劃，定位欠缺索引
• 重複查詢檢測：自動標記相同 SQL 多次執行（N+1 問題）
• 內存/時間統計：請求級性能概覽
• Active Record 追蹤：顯示模型方法調用對應的 SQL

3. 常見衝突解決

若與其他調試擴展衝突導致 SQL 不顯示，嘗試禁用其他路由：

'routes' => array(
    // 暫時註釋掉 CWebLogRoute
    // array('class' => 'CWebLogRoute', 'levels' => 'trace', 'categories' => 'system.db.*'),
    array('class' => 'ext.yii-debug-toolbar.YiiDebugToolbarRoute', 'ipFilters' => array('127.0.0.1')),
),

方案三：程序化調試（代碼級控制）

1. 直接輸出 SQL

// 方法一：CDbCommand::getText()
$command = Yii::app()->db->createCommand()
    ->select('*')
    ->from('user')
    ->where('status=:status', array(':status' => 1));
echo $command->getText(); // SELECT * FROM `user` WHERE `status`=:status

// 方法二：開啟單條 SQL 分析
$command->queryAll(); // 執行後
var_dump($command->getText(), $command->getParams());

2. 模型級調試

class User extends CActiveRecord {
    public function beforeFind() {
        if (YII_DEBUG) {
            Yii::trace('User query: ' . $this->getDbCriteria()->toString(), 'myapp.db');
        }
        return parent::beforeFind();
    }
}

方案四：生產環境安全調試

1. 條件式開啟

// 僅特定用戶/參數開啟
if (isset($_GET['sql_debug']) && Yii::app()->user->isAdmin()) {
    Yii::app()->db->enableProfiling = true;
    Yii::app()->db->enableParamLogging = true;
}

2. 慢查詢記錄

'db' => array(
    'class' => 'CDbConnection',
    'enableProfiling' => true,
    'onAfterQuery' => function($event) {
        $sql = $event->sender->getText();
        $time = $event->sender->queryDuration;
        if ($time > 1.0) { // 超過 1 秒記錄
            Yii::log("Slow Query ($time s): $sql", 'warning', 'db.slow');
        }
    },
),

調試輸出解讀指南

最佳實踐總結

1. 開發階段：常駐 Debug Toolbar，實時監控 SQL 質量
2. 代碼審查：關注循環中查詢、關聯載入策略（with/join）
3. 上線前：關閉 YII_DEBUG，啟用慢查詢日誌告警
4. 線上排查：條件式開啟分析，配合 EXPLAIN 定位瓶頸
5. 長期優化：建立 SQL 基線指標，定期回歸測試