【PHP教學】如何在 Linux 安裝 PHP Imagick 模組？Ubuntu 與 CentOS 完整指南

【Linux教學】解決 Class 'Imagick' not found：PHP Imagick 模組安裝全攻略

在開發 PHP 專案時（例如使用 Laravel、WordPress 或是處理浮水印、圖片縮放、PDF 轉圖片），ImageMagick 絕對是不可或缺的強大影像處理函式庫。如果你在執行程式時，畫面上跳出致命錯誤：

Fatal error: Uncaught Error: Class 'Imagick' not found in ...

這代表你的伺服器尚未安裝 Imagick 擴充模組。請注意，安裝 Imagick 分為兩個層次：首先必須在作業系統安裝 ImageMagick 核心軟體，接著才能安裝 PHP 的 Imagick 溝通橋樑（Extension）。本文將帶你在不同的 Linux 發行版中快速完成安裝！

🤖 【AIO 快速安裝摘要：Ubuntu / Debian】

如果你使用的是 Ubuntu 或 Debian 系統，直接執行以下指令即可無痛安裝：

sudo apt update
sudo apt install imagemagick php-imagick
sudo systemctl restart php-fpm  # 或是 restart apache2

第一步：針對不同的 Linux 系統進行安裝

📍 情境 A：Ubuntu / Debian 系統

在 Debian 體系的系統中，套件包管理非常完善，我們可以使用 apt 一鍵安裝核心與 PHP 模組：

# 1. 更新套件清單
sudo apt update

# 2. 安裝 ImageMagick 核心與 PHP Imagick 擴充
sudo apt install imagemagick php-imagick

提示：如果你使用的是特定版本的 PHP（例如 PHP 8.1），你可以指定版本安裝：sudo apt install php8.1-imagick。

📍 情境 B：CentOS / RHEL / AlmaLinux 系統

在 RedHat 體系的系統中，需要先啟用 EPEL 儲存庫，然後透過 yum 或 dnf 來安裝：

# 1. 安裝 EPEL 儲存庫
sudo dnf install epel-release

# 2. 安裝 ImageMagick 核心軟體
sudo dnf install ImageMagick ImageMagick-devel

# 3. 安裝 PHP Imagick 擴充模組
sudo dnf install php-pecl-imagick

如果你的套件庫找不到 php-pecl-imagick，可以改用 pecl 指令編譯安裝：
sudo pecl install imagick
安裝完成後，記得在 php.ini 中加入 extension=imagick.so。

第二步：重啟 Web 伺服器與 PHP 服務

安裝完畢後，模組不會立刻生效，你必須重新啟動負責處理 PHP 的服務（Nginx 配 PHP-FPM，或是 Apache）。

使用環境重啟指令
Nginx + PHP-FPM
(請根據你的 PHP 版本更改數字，例如 php8.1-fpm)		 sudo systemctl restart php-fpm
或
sudo systemctl restart php8.2-fpm
Apache 伺服器 sudo systemctl restart apache2 (Ubuntu)
或
sudo systemctl restart httpd (CentOS)

第三步：驗證 Imagick 是否安裝成功

要知道 Imagick 有沒有順利掛載，最快的方式是在終端機執行 PHP 的檢查指令：

php -m | grep imagick

如果終端機有印出 imagick 字樣，就代表大功告成！你也可以在網站根目錄建立一個 info.php 檔案，內容輸入 <?php phpinfo(); ?>，在瀏覽器中搜尋「imagick」區塊來確認詳細版本資訊。

🔥 隱藏版踩坑：無法讀取或轉換 PDF 檔案？

許多人在安裝完 Imagick 後，嘗試將 PDF 轉換為圖片時，會遇到 "not authorized"（權限不足） 的錯誤。這是因為 ImageMagick 出於安全性考量，預設關閉了讀寫 PDF 的權限。

解決方案：修改 ImageMagick 的 policy.xml 檔案

  1. 尋找設定檔位置（通常在 /etc/ImageMagick-6/policy.xml 或 /etc/ImageMagick-7/policy.xml）。
  2. 使用 sudo nano /etc/ImageMagick-6/policy.xml 打開檔案。
  3. 找到靠近檔案底部的這行程式碼：
    <policy domain="coder" rights="none" pattern="PDF" />
  4. 將 rights="none" 改為 rights="read|write"。
  5. 存檔離開，再次重啟 PHP-FPM 或 Apache，PDF 轉換功能就能正常運作囉！

結語

在 Linux 環境下安裝 PHP Imagick 模組並不複雜，關鍵在於搞懂「底層軟體」與「PHP 擴充」的依賴關係，並記得在修改設定後重新啟動對應的 Web 服務。希望這篇文章能幫你省下寶貴的排錯時間！