ServBay PHP 故障排除：解決 ImageMagick 與大檔案上傳等常見問題

ServBay 為開發者提供便捷的本地 Web 開發環境，支援多種 PHP 版本及豐富的擴充套件。雖然 ServBay 致力於提供穩定可靠的服務，但在實際開發過程中，使用者偶爾仍會遇到 PHP 服務或特定擴充模組相關的故障。

本文旨在協助您診斷及解決 ServBay 中常見的 PHP 相關問題，重點說明 ImageMagick 擴充錯誤與 PHP 上傳大檔案時速度下降這兩個情境，並提供詳細排查步驟及解決方案。

常見的 PHP 故障及解決方案

以下提供一些常見 PHP 以及其擴充套件會遇到的問題與解決方式。

ImageMagick「number of supported formats: 0」錯誤

問題描述：

部分 ServBay 使用者在使用 ImageMagick PHP 擴充時，可能遇到下列錯誤提示：

ImageMagick number of supported formats: 0

這通常代表 ImageMagick 函式庫本身未能正確識別或載入可支援的圖片格式。

解決方案：

此問題通常與 ServBay Runtime 提供的底層函式庫相關。請依照下列步驟進行排查與修復：

1. 開啟 ServBay 應用程式。
2. 於左側導覽列選取 套件（Packages）。
3. 在右側套件列表中，找到並點選 ServBay Runtime。
4. 確認 ServBay Runtime 已安裝，且版本號為 1.0.20 或 1.1.20 以上。若您的版本較舊，請點擊升級按鈕，將其更新至最新版。
5. ServBay Runtime 升級完成後，請重啟正在使用的 PHP 服務（例如 PHP 8.1, PHP 8.2 等）。

原理說明： ServBay Runtime 套件內含了 ServBay 內部元件及部份 PHP 擴充模組所需的共享函式庫。升級 Runtime 可取得最新版本的函式庫，解決 ImageMagick 無法正確載入圖片格式支援的問題。

PHP 上傳大檔案時速度下降

問題描述：

部分使用者在 PHP 應用（如基於 Tus-PHP 的服務、NextCloud 等）上傳超過 1GB 的大型檔案時，會發現上傳速度顯著下降。

造成這類現象的原因，可能與 php-fpm 的處理方式，以及檔案分段（Chunked Transfer Encoding）的交互有關。

解決方案：

可嘗試以下方法改善大檔案上傳效能：

1. 提升 php-fpm 的 pm.max_children 數量

   ServBay 預設 php-fpm 設定中，pm.max_children（最大子行程數）通常設為 10。在處理大量並發請求，或需長時間占用行程的巨型檔案上傳時，子行程數過低會成為瓶頸。

   您可以酌情提高此數值。同時，請檢查 pm 設定（如 pm = dynamic 或 pm = ondemand）是否最符合您的工作負載。

   

   操作步驟：

   • 於 ServBay 左側導覽列，選擇您所使用的 PHP 版本（例如 PHP 8.2）。
   • 點選右側的 Configuration 按鈕。
   • 找到 php-fpm.conf 檔案並開啟。
   • 搜尋 pm.max_children，調整其數值。
   • 儲存檔案並重啟該 PHP 服務。

   原理說明： 增加子行程數可讓 php-fpm 同時處理更多請求。對於如大檔案上傳這類可能長時間占用單一行程的任務，提供更多可用子行程可減少等待時間，提升整體效率。

2. 停用檔案分段（於應用程式端，非建議在 ServBay 層面調整）

   此做法不甚推薦，因為需要調整您的應用程式程式碼，且可能會影響一些賴以分段傳輸的功能。但在部分特定場景下，可於客戶端或伺服端程式碼停用或調整檔案分段機制，來避免與 php-fpm 間可能產生的速度問題。

3. 檢查並調整 Web 伺服器（Nginx/Caddy）的 fastcgi_request_buffering 參數

   若您使用 Nginx 或 Caddy 作為 Web 伺服器並將請求轉發給 php-fpm，fastcgi_request_buffering 參數會影響伺服器如何將請求主體傳遞到 FPM。

   • Nginx： Nginx 預設開啟 fastcgi_request_buffering on;，即會完整接收客戶端上傳檔案後再一次傳送給 php-fpm。對於大檔案，這將導致 FPM 在接收到資料前會有明顯延遲。將此參數調為 fastcgi_request_buffering off; 可使 Nginx 在接收資料時同步將資料流傳給 FPM，處理大型檔案上傳時更加高效。

     location ~ \.php$ {
         # ... 其他 fastcgi 參數 ...
         fastcgi_request_buffering off; # 新增或修改此行
         # ...
     }

   • Caddy： Caddy 的 php_fastcgi 指令預設行為類似 fastcgi_request_buffering off，會以串流方式傳遞請求主體。若遇到上述問題，一般不需調整 Caddy 設定。但如有自訂 reverse_proxy 配置轉發至 FPM，也要確認未引入額外緩衝機制。

   操作步驟：

   • 在 ServBay 左側導覽列選擇您所用的 Web 伺服器（如 Nginx 或 Caddy）。
   • 點選右側的 Configuration 按鈕。
   • 尋找主設定檔（如 nginx.conf 或 Caddyfile）並開啟。
   • 於處理 PHP 請求的 location 區塊（Nginx）或 php_fastcgi 區塊（Caddy）中，新增或修改 fastcgi_request_buffering off;。
   • 儲存檔案並重啟該 Web 伺服器服務。

其他相關檢查：

• 檢查 PHP 設定 (php.ini)： 確認 upload_max_filesize、post_max_size、及 memory_limit 等指令數值足夠大，以支援目標檔案大小。這些設定過低雖會導致上傳失敗（而非速度慢），但亦屬常見檢查項目。
• 檢查日誌檔案： 查看 Web 伺服器（Nginx/Caddy）錯誤日誌與存取日誌，以及 PHP-FPM 的錯誤日誌。這些日誌通常會紀錄更詳細的錯誤原因或請求過程發生的異常，有助於問題定位。PHP 錯誤日誌路徑可於 php.ini 中的 error_log 指令查詢。

通用 PHP 故障排除技巧

當您於 ServBay 環境遇到 PHP 相關問題時，可依這些通用流程進行排查：

1. 檢查 PHP 版本及擴充套件： 確認所用之 PHP 版本與應用程式相容，並已安裝且啟用必須的 PHP 擴充模組（如 ImageMagick、GD、MySQLi 等）。可建立只含 phpinfo() 函數的 PHP 檔案，於瀏覽器端查看詳細設定資訊。
2. 檢查 ServBay 服務狀態： 檢查所用 PHP 服務（例如 PHP 8.2）、Web 伺服器（Nginx 或 Caddy），以及相關資料庫服務（如 MySQL、PostgreSQL）皆於 ServBay 中正常執行。
3. 查看錯誤日誌： 這是診斷問題最關鍵的一步。
   • PHP 錯誤日誌： 查看 php.ini 檔案中 error_log 指定的日誌檔，並確保開發環境下 display_errors 設為 On（正式環境一般為 Off），log_errors 設定為 On。
   • Web 伺服器日誌： 檢查 Nginx 或 Caddy 的錯誤日誌檔案。通常位於 ServBay 安裝目錄底下的 logs 資料夾，或於 Web 伺服器設定檔中所指定。
   • ServBay 應用日誌： ServBay 應用程式本身亦可能有日誌紀錄關鍵事件或啟動異常。
4. 簡化測試環境： 如可行，於極簡化的測試環境（例如單一 PHP 測試檔）重現問題，以排除業務邏輯或程式複雜性的因素。
5. 參閱 ServBay 文件與社群： ServBay 官方文件與使用者社群亦是不容忽視的協助管道，可取得更多既有問題解法。

總結

本文針對 ServBay 中常見的 ImageMagick 錯誤及大檔案上傳速度緩慢問題，提供具體解決方案，並補充通用 PHP 故障排除技巧。透過檢查 ServBay Runtime 版本、調整 php-fpm 參數、優化 Web 伺服器快取設定，以及細讀日誌，多數 PHP 相關問題都可於 ServBay 環境中解決。若問題依然無解，強烈建議善用日誌進行深入分析，或尋求社群的協助。