Sphinx API 呼叫失敗除錯：GetLastError() 關鍵技巧

使用 Sphinx/Coreseek PHP API 時，Query() 方法失敗僅回傳 false，不會直接輸出錯誤訊息。掌握 GetLastError() 方法是快速定位問題的關鍵。

常見失敗場景

$cl = new SphinxClient();
$cl->SetServer('localhost', 9312);

$res = $cl->Query($keyword, 'my_index');
// $res === false 表示失敗，但不知原因

一行程式碼取得詳細錯誤

var_dump($cl->GetLastError());

典型錯誤訊息與對應解決方案

完整除錯範本

function sphinx_search($keyword, $index = '*') {
    $cl = new SphinxClient();
    $cl->SetServer('localhost', 9312);
    $cl->SetConnectTimeout(1);
    $cl->SetArrayResult(true);
    $cl->SetLimits(0, 20, 1000);
    $cl->SetMatchMode(SPH_MATCH_EXTENDED);

    $res = $cl->Query($keyword, $index);
    
    if ($res === false) {
        $err = $cl->GetLastError();
        error_log("Sphinx search failed: keyword='$keyword', index='$index', error=$err");
        // 可選：拋出例外、回傳空陣列、降級到 DB LIKE 查詢
        return [];
    }
    
    return $res['matches'] ?? [];
}

進階除錯技巧

• 查詢日誌：searchd 啟用 query_log，可見實際收到的查詢語句與耗時。
• 驗證索引：indexer -c sphinx.conf --check idx_main 檢查索引完整性。
• 網路抓包：tcpdump -i lo port 9312 -w sphinx.pcap 分析協議交互。
• 版本相容性：Sphinx 2.x/3.x API 介面基本相容，但 Coreseek 基於 0.9.9/2.x，建議使用對應版本 sphinxapi.php。

核心口訣：Query() 回傳 false → 立即呼叫 GetLastError() → 讀取錯誤字串 → 對照上表 → 定位解決。別讓「靜默失敗」拖慢排查速度。