macOS Homebrew PHP 手動編譯插件啟用指南

本文件記錄在 macOS 環境下，使用 Homebrew 安裝的 PHP（以 PHP 8.5 為例）手動編譯插件（.so 檔案，以 BLAKE3 為例）後的啟用流程與載入順序觀念。

📋 快速啟用三步驟

假設編譯完成的插件路徑為：/opt/homebrew/Cellar/php/8.5.6/pecl/20250925/blake3.so

步驟 1：建立獨立的 .ini 設定檔

Homebrew PHP 會自動掃描 conf.d 目錄下的所有設定檔。在該目錄下建立一個新檔案：

nano /opt/homebrew/etc/php/8.5/conf.d/20-blake3.ini

步驟 2：寫入插件載入宣告

在檔案中填入插件的絕對路徑：

• 一般插件（如 Redis, Swoole, MongoDB 等）：

  extension="/opt/homebrew/Cellar/php/8.5.6/pecl/20250925/blake3.so"
  

• 除錯或核心效能插件（如 Xdebug, OPcache 等）：

  zend_extension="/opt/homebrew/Cellar/php/8.5.6/pecl/20250925/xdebug.so"
  

步驟 3：重啟服務與驗證

• 重啟 PHP-FPM 服務（常搭配 Nginx/Apache）：

  brew services restart php
  

• 驗證插件是否成功載入：

  # 檢查 CLI 模式下是否有該插件
  php -m | grep -i blake3
  
  # 檢查 PHP 是否有正確讀取到該設定檔
  php --ini
  

🔍 進階知識：conf.d 檔名中的數字含意（載入順序）

在 conf.d/ 目錄中，設定檔的命名通常會帶有數字前綴（例如 20-my_extension.ini），這是為了控制插件的載入先後順序。

1. 為什麼需要數字？

PHP 在啟動時，會純粹依照「檔名字母與數字的 ASCII 順序」由上往下依序讀取 conf.d/ 內的檔案。如果插件之間有相依性（例如：A 插件必須在 B 插件啟動後才能運作），就必須利用數字來排定先後。

2. 常見的命名與排序規範

• 10-*.ini（核心/效能插件）： 通常是最底層、最需要優先載入的套件（如 10-opcache.ini）。
• 20-*.ini（基礎擴充）： 一般獨立的擴充模組，或資料庫基礎模組（如 20-pdo.ini）。
• 30-*.ini（依賴型擴充）： 必須在基礎模組之後才能執行的子模組（如 30-pdo_mysql.ini，它必須等 pdo 載入後才能正常運作）。

3. 建議命名

若手動編譯的插件很單純、沒有依賴其他插件，命名為 20-插件名.ini 或 50-插件名.ini 即可。

📂 常見預設路徑速查表（以 PHP 8.5 為例）