解決 phpMyAdmin "require_once(./libraries/common.inc.php) failed" 錯誤完整指南

錯誤現象

安裝 phpMyAdmin 後訪問頁面，出現以下致命錯誤：

Warning: require_once(./libraries/common.inc.php): failed to open stream: No such file or directory in ...\index.php on line 36
Fatal error: require_once(): Failed opening required './libraries/common.inc.php' (include_path='.;C:\php5\pear') in ...\index.php on line 36

根因分析

phpMyAdmin 入口腳本 index.php 使用相對路徑 ./libraries/... 載入核心庫。錯誤原因通常為：

1. 安裝目錄位於磁碟根目錄 (如 D:\phpmyadmin)，導致相對路徑解析異常。
2. 目錄權限不足，Web 伺服器進程 (IIS_IUSRS / IUSR / apache) 無法讀取 libraries 目錄及其父目錄。
3. PHP open_basedir 限制 未包含 phpMyAdmin 目錄。
4. 符號連結/虛擬目錄配置錯誤，導致工作目錄與實際路徑不符。

解決方案

方法一：避免安裝在磁碟根目錄 (Windows)

將 phpMyAdmin 移至子目錄，例如：

D:\WebSites\phpmyadmin
D:\Projects\Tools\phpmyadmin

並更新 Web 伺服器虛擬目錄指向新路徑。

方法二：設定正確的目錄權限 (Windows / IIS)

1. 右鍵 phpMyAdmin 目錄 → 「內容」 → 「安全性」 → 「編輯」。
2. 新增用戶：IIS_IUSRS、IUSR (或對應的應用程式池身分)。
3. 授予權限：「讀取和執行」、「列出資料夾內容」、「讀取」。
4. 確保父目錄 (如 D:\WebSites) 同樣具備上述權限。

方法三：Linux/Apache 環境權限修正

chown -R apache:apache /var/www/html/phpmyadmin
chmod -R 755 /var/www/html/phpmyadmin
chmod 644 /var/www/html/phpmyadmin/config.inc.php
# 若使用 php-fpm，用戶組改為 www:www

方法四：調整 PHP open_basedir 設定

編輯 php.ini 或 Apache php_admin_value：

; php.ini
open_basedir = "/var/www/html/:/tmp/:/usr/share/php/:/var/www/html/phpmyadmin/"

; 或 Apache VirtualHost 內
php_admin_value open_basedir "/var/www/html/:/tmp/:/usr/share/php/:/var/www/html/phpmyadmin/"

重啟 PHP-FPM / Apache 生效。

方法五：修正 config.inc.php 絕對路徑 (終極方案)

編輯 config.inc.php，將 $cfg['PmaAbsoluteUri'] 設為完整 URL：

$cfg['PmaAbsoluteUri'] = 'https://your-domain.com/phpmyadmin/';

此設定強制 phpMyAdmin 使用絕對路徑生成連結與載入資源，繞過相對路徑解析問題。

驗證步驟

1. 瀏覽器訪問 phpMyAdmin URL，確認無錯誤訊息。
2. 嘗試登入、瀏覽資料庫、執行 SQL、匯出/匯入功能。
3. 檢查瀏覽器開發者工具 Network 標籤，確認無 404/500 請求。

預防措施

• 使用套件管理器安裝 (如 yum install phpmyadmin、apt install phpmyadmin) 可自動處理路徑與權限。
• 部署腳本中包含權限設定、open_basedir 更新、配置檔絕對路徑寫入。
• 定期更新 phpMyAdmin 至最新版，修補已知路徑解析 Bug。

相關錯誤變體快速對照