PHP 程序調試完全指南：錯誤報告、Xdebug、日誌、性能分析與業務邏輯排查

PHP 程序調試完全指南：錯誤報告、Xdebug、日誌、性能分析與業務邏輯排查

調試是開發核心技能。本文系統覆蓋 PHP 內建錯誤機制、Xdebug/ZendDebugger 進階工具、業務邏輯排查方法論、非功能性問題 (內存、性能、死循環) 定位、單元測試與生產環境最佳實踐。

一、PHP 內建錯誤報告：開發 vs 生產環境分離

開發環境 (php.ini)

; 顯示所有錯誤、警告、通知、嚴格標準
error_reporting = E_ALL | E_STRICT
display_errors = On
display_startup_errors = On
log_errors = On
error_log = /var/log/php/dev_error.log

生產環境 (php.ini)

; 隱藏詳細錯誤，記錄日誌
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /var/log/php/prod_error.log
; 可選：syslog、發送郵件、Sentry 等
; error_log = syslog

關鍵原則

• 開發環境開啟 `E_STRICT`：捕獲編碼標準問題、未聲明變量 (如 `Notice: Undefined variable` 常隱藏 Bug)
• 生產環境絕不 `display_errors`：洩露路徑、SQL、堆棧給攻擊者
• 第三方庫若產生大量 Notice：考慮替換，優質庫應零 Notice
• 慎用 `@` 抑制符：吞沒錯誤導致排查極難，僅用於已知可忽略的 `fopen` 等

二、內建函數的調試參數

網絡/資源函數常提供錯誤代碼/字串輸出參數：

<?php
$fp = fsockopen('example.com', 80, $errno, $errstr, 30);
if (!$fp) {
    // $errno: 系統錯誤碼, $errstr: 可讀描述
    error_log("連接失敗: $errstr ($errno)");
    // 處理失敗...
}

// 類似函數：pfsockopen, stream_socket_client, stream_socket_server
// 數據庫：mysqli_connect_errno(), mysqli_connect_error()
// Socket：socket_last_error(), socket_strerror()
?>

三、進階調試工具：Xdebug (業界標準)

安裝與基礎配置 (php.ini)

zend_extension=xdebug.so
xdebug.mode = debug,develop,trace,profile
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.var_display_max_depth = 5
xdebug.var_display_max_children = 256
xdebug.var_display_max_data = 1024

核心功能

PhpStorm + Xdebug 快速上手

1. 安裝 Xdebug，配置 `xdebug.mode=debug`、`xdebug.client_port=9003`
2. PhpStorm: `Run > Start Listening for PHP Debug Connections`
3. 瀏覽器安裝 Xdebug Helper 擴展，設置 IDE Key = `PHPSTORM`
4. 代碼行號處點擊設置斷點 (紅點)
5. 訪問頁面，PhpStorm 自動暫停，變量面板檢查狀態

四、業務邏輯錯誤排查方法論

1. 明確預期 vs 實際：具體輸入、預期輸出、實際輸出
2. 定位相關代碼片段：路由 → 控制器 → Service → Repository → SQL
3. 肉眼審查：邊界條件、類型轉換、邏輯運算符優先級、狀態機漏轉
4. 關鍵變量輸出：`var_dump()`、`error_log()`、Xdebug 斷點觀察
5. 二分法縮小範圍：註釋一半代碼、中間斷點驗證、逐步逼近
6. 複現最小案例：提取核心邏輯寫單元測試，隔離環境因素

五、運行日誌：不可中斷腳本的救命稻草

<?php
// 簡易日誌類
class Logger {
    private $path;
    public function __construct($file = 'runtime.log') {
        $this->path = sys_get_temp_dir() . "/$file";
    }
    public function info($msg, $context = []) {
        $this->write('INFO', $msg, $context);
    }
    public function error($msg, $context = []) {
        $this->write('ERROR', $msg, $context);
    }
    private function write($level, $msg, $context) {
        $line = sprintf(
            "[%s] %s: %s %s\n",
            date('Y-m-d H:i:s'),
            $level,
            $msg,
            $context ? json_encode($context, JSON_UNESCAPED_UNICODE) : ''
        );
        file_put_contents($this->path, $line, FILE_APPEND | LOCK_EX);
    }
}

// 關鍵點記錄
$log = new Logger('payment.log');
$log->info('支付回調收到', ['order_id' => $orderId, 'amount' => $amount]);
// ...
$log->error('簽名驗證失敗', ['order_id' => $orderId, 'sign' => $sign]);
?>

關鍵記錄點

• 外部 API 請求/回應 (含耗時)
• 資源獲取失敗 (DB 連接、Redis、文件鎖)
• 權限檢查失敗
• 狀態機流轉 (訂單: 待付款 → 已付款 → 發貨 → 完成)
• 定時任務開始/結束/異常

六、非功能性問題定位

七、單元測試：以代碼測代碼

<?php
// PHPUnit 示例
class CartTest extends TestCase {
    public function testAddItemUpdatesQuantity() {
        $cart = new Cart();
        $cart->add('SKU001', '商品', 100, 1);
        $cart->add('SKU001', '商品', 100, 2);
        
        $this->assertEquals(3, $cart->getQty('SKU001'));
        $this->assertEquals(300, $cart->total());
    }
    
    public function testEmptyCartThrowsOnCheckout() {
        $this->expectException(EmptyCartException::class);
        (new Cart())->checkout();
    }
}
?>

TDD 循環：紅 (寫失敗測試) → 綠 (最小實現通過) → 重構 (優化代碼保持綠燈)

八、生產環境調試原則

• **不可直接在生產斷點/var_dump** (阻塞進程、洩露數據)
• **日誌為主**：結構化 JSON 日誌 + ELK/日誌平台檢索
• **指標監控**：Prometheus + Grafana 監控 QPS、延遲、錯誤率、內存、CPU
• **分布式追蹤**：SkyWalking/Jaeger 追蹤跨服務調用鏈
• **異常捕獲平台**：Sentry/Bugsnag 自動聚合異常、告警、版本關聯
• **影子表/只讀副本**：排查數據問題時查副本，不影響主庫