PHP 中 return 報錯與 mysqli 連接失敗的排查指南

問題現象

開發者在函數中使用 return $db 返回資料庫連接資源時觸發 HTTP 500 錯誤；同時發現凡是涉及 mysqli_* 系列函數的代碼均報錯，懷疑是 PHP 版本或擴展配置問題。

核心原因分析

1. mysqli 擴展未啟用

mysqli 並非 PHP 內置默認啟用，需在 php.ini 中開啟：

;extension=php_mysqli.dll  →  extension=php_mysqli.dll

修改後必須重啟 Web 服務（Apache/Nginx + PHP-FPM）。可通過 phpinfo() 或 php -m 驗證 mysqli 是否出現在模塊列表中。

2. 函數作用域導致變量不可見

原始代碼片段：

function db_connect() {
    @$db = mysqli_connect('localhost','root','8251617','bookmarks');
    if (!$db) {
        throw new Exception('Could not connect to database server');
    } else {
        return $db;
        echo 'dddd'; // 永遠不會執行
    }
}

關鍵點：return 之後的代碼不會執行，但這不會導致 500 錯誤。真正的 500 來源於 mysqli_connect 因擴展缺失而拋出的致命錯誤，或連接參數錯誤（主機、用戶名、密碼、數據庫名）。

3. 錯誤抑制符 @ 掩蓋了真實錯誤

@$db = mysqli_connect(...) 會吞噬警告/錯誤信息，導致調試困難。建議開發環境移除 @，或統一使用異常處理：

function db_connect(): mysqli {
    $db = new mysqli('localhost', 'root', '8251617', 'bookmarks');
    if ($db->connect_errno) {
        throw new RuntimeException("MySQL 連接失敗: {$db->connect_error}");
    }
    $db->set_charset('utf8mb4');
    return $db;
}

排查步驟清單

1. 執行 php -m | grep mysqli 確認擴展已加載。
2. 檢查 php.ini 中 extension_dir 路徑是否正確，DLL/so 文件是否存在。
3. 用獨立腳本測試：php -r "new mysqli('localhost','root','pass','db');" 觀察輸出。
4. 確認 MySQL 服務運行中，端口 3306 可達，用戶權限正確。
5. 查看 Web 服務器錯誤日誌（Apache error.log、Nginx error.log、PHP-FPM 錯誤日誌）獲取完整堆棧。

最佳實踐建議

• 使用面向對象風格 new mysqli() 替代過程式風格，異常處理更直觀。
• 生產環境關閉 display_errors，開啟 log_errors，錯誤寫入日誌文件。
• 資料庫憑證不要硬編碼，使用環境變量或配置文件（如 .env）。
• 連接對象建議單例或連接池復用，避免頻繁建立連接。

總結

「return 報錯」實際上是 mysqli 擴展未啟用 或 連接參數錯誤 導致的致命錯誤被 @ 隱藏；函數作用域問題僅影響變量可見性，不會直接拋出 500。啟用擴展、移除抑制符、善用異常處理，即可徹底解決。