PHP 部署 Azure 連不上 Blob Storage：缺少 PEAR 導致 500 錯誤

故障現象

本地 Apache/IIS 運行正常，發布至 Azure Web Apps 後訪問報 HTTP 500，錯誤詳情顯示 FastCgiModule 處理 PHP56_via_FastCGI 失敗，代碼異常點在 ServicesBuilder::getInstance()->createBlobService($constr)。

根本原因

Azure PHP 運行時預設未安裝 PEAR（PHP Extension and Application Repository），而 Azure SDK for PHP 依賴 PEAR 中的 HTTP_Request2、Mail_mime 等包。本地環境通常已全局安裝 PEAR，導致開發階段未發現缺失。

解決方案

1. 在項目中包含 PEAR 依賴：使用 Composer 管理依賴（推薦）。

   composer require pear/http_request2 pear/mail_mime
   

2. 或手動上傳 PEAR 目錄：將本地 pear 目錄隨代碼部署，並在 php.ini 中設定 include_path 指向該目錄。
3. Azure 門戶啟用擴展：在「配置」→「常規設置」→「PHP 版本」下勾選所需擴展（若可用）。

驗證方法

<?php
// 測試腳本
require_once 'HTTP/Request2.php';
echo "PEAR HTTP_Request2 loaded OK";
?>

部署後訪問該腳本，若無錯誤則 PEAR 已正常加載。

最佳實踐

• 採用 Composer 管理所有第三方依賴，避免環境差異。
• 使用 Azure SDK for PHP 最新版（v2+），已減少對 PEAR 的依賴。
• 部署前在本地模擬 Azure 環境（Docker 映像 mcr.microsoft.com/azure-functions/php）測試。