Linux (CentOS 7) 手動編譯 PHP 插件啟用指南

本文件記錄在 CentOS 7 環境下，從原始碼手動編譯 PHP 插件（.so 檔案，以 BLAKE3 為例）後的啟用流程與載入順序觀念。

📋 快速啟用三步驟

假設編譯完成的插件路徑為：/usr/lib64/php/modules/blake3.so，PHP 版本為 8.3（API 版本 20230831）。

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

CentOS 7 的 PHP 預設會自動掃描 /etc/php.d/ 目錄下的所有設定檔。在該目錄下建立一個新檔案：

sudo nano /etc/php.d/20-blake3.ini

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

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

一般插件（如 Redis, Swoole, MongoDB 等）：
```
extension="/usr/lib64/php/modules/blake3.so"
```
除錯或核心效能插件（如 Xdebug, OPcache 等）：
```
zend_extension="/usr/lib64/php/modules/xdebug.so"
```

步驟 3：重啟服務與驗證

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

# CentOS 7 使用 systemctl（推薦）
sudo systemctl restart php-fpm

# 或使用 service（舊式，仍可用）
sudo service php-fpm restart

驗證插件是否成功載入：

# 檢查 CLI 模式下是否有該插件
php -m | grep -i blake3

# 檢查 PHP 是否有正確讀取到該設定檔
php --ini

🔄 替代方式：直接在 `php.ini` 中新增擴展

上述三步驟是利用 /etc/php.d/ 目錄進行模組化管理。但也可以選擇將擴展宣告直接寫入主設定檔 php.ini：

步驟（簡版）

編輯 /etc/php.ini
在檔案最後添加一行：
```
extension=blake3.so
```
（不需要完整路徑，見下方 extension_dir 說明）
重啟 PHP-FPM：sudo systemctl restart php-fpm

兩種方式的比較

方式	位置	優點	缺點	適用情況
`/etc/php.d/` 方式	`/etc/php.d/20-blake3.ini`	模組化、清晰、支援載入順序、易於維護	需要額外目錄結構	推薦：管理多個擴展
直接在 `php.ini`	`/etc/php.ini` 最後一行	簡潔、無需建立額外檔案	配置檔易變冗長、不利於載入順序管理	單一或少量擴展

🔍 進階知識：擴展搜尋與載入機制

1. `extension_dir` 與相對路徑

當妳在設定檔中寫 extension=blake3.so 時，PHP 不是直接尋找絕對路徑，而是去查詢 extension_dir 設定值，然後在該目錄下尋找該檔案。

CentOS 7 上透過系統套件安裝的 PHP 預設會自動設定 extension_dir 為 /usr/lib64/php/modules/：

extension_dir => /usr/lib64/php/modules => /usr/lib64/php/modules

所以 extension=blake3.so 會自動解析為 /usr/lib64/php/modules/blake3.so。

驗證妳的 PHP 設定：

php -i | grep "extension_dir"

這也解釋了為什麼直接在 php.ini 中加 extension=blake3.so 也能運作 — 因為擴展檔案已經位於 extension_dir 指定的目錄中。

2. `/etc/php.d/` 檔名中的數字含意（載入順序）

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

為什麼需要數字？

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

常見的命名與排序規範

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

建議命名

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

📂 常見預設路徑速查表（CentOS 7 + PHP 8.3）

項目	預設路徑
PHP 主設定檔	`/etc/php.ini`
插件自動掃描目錄	`/etc/php.d/`
編譯後的插件位置	`/usr/lib64/php/modules/`
擴展搜尋目錄	`/usr/lib64/php/modules/`
PHP-FPM 設定檔	`/etc/php-fpm.conf`
PHP-FPM 池設定	`/etc/php-fpm.d/www.conf`

💡 最佳實踐建議

即使兩種方式都能運作，推薦優先使用 /etc/php.d/ 方式，原因如下：

可擴展性 — 當需要管理多個擴展時，/etc/php.d/ 方式更清晰、更易維護
載入順序管理 — 數字前綴讓擴展相依性的管理更直觀
配置隔離 — 每個擴展各有獨立的設定檔，避免 php.ini 變得過於冗長
未來升級 — 如果當前只有一個擴展，但未來需要增加，遷移至 /etc/php.d/ 方式相對簡單

從 `php.ini` 遷移至 `/etc/php.d/` 的步驟

如果妳的 CentOS 7 伺服器上已經用 extension=blake3.so 方式運作，但想要遷移到模組化管理：

# 1. 建立新的設定檔（若 /etc/php.d/ 已存在，直接使用）
sudo nano /etc/php.d/20-blake3.ini

# 2. 在新檔案中填入：
#    extension="/usr/lib64/php/modules/blake3.so"
#    （或簡寫為 extension=blake3.so，二者都可）

# 3. 編輯 php.ini，刪除那一行 extension=blake3.so
sudo nano /etc/php.ini

# 4. 重啟 PHP-FPM
sudo systemctl restart php-fpm

# 5. 驗證
php -m | grep -i blake3

🔄 CentOS 7 與 macOS Homebrew 的差異

面向	CentOS 7（yum/remi）	macOS Homebrew
安裝來源	系統套件管理（yum / remi）	Homebrew 套件管理
主設定檔	`/etc/php.ini`	`/opt/homebrew/etc/php/x.x/php.ini`
插件目錄	`/etc/php.d/`	`/opt/homebrew/etc/php/x.x/conf.d/`
插件存放	`/usr/lib64/php/modules/`	`/opt/homebrew/Cellar/php/x.x.x/pecl/xxxxxxxx/`
重啟 FPM	`systemctl restart php-fpm`	`brew services restart php`
重啟 CLI	無需重啟（直接執行）	無需重啟（直接執行）

💡 實踐筆記

編譯 BLAKE3 插件時，使用如下流程：

從原始碼或 PECL 取得插件原始碼
執行 phpize 進行設定預處理
執行 ./configure 與 make 進行編譯
使用 sudo make install 複製到 /usr/lib64/php/modules/blake3.so
在 /etc/php.d/20-blake3.ini 中聲明 extension="/usr/lib64/php/modules/blake3.so"
執行 sudo systemctl restart php-fpm 重啟 PHP-FPM
執行 php -m | grep -i blake3 驗證載入成功