gmagick扩展需手动编译安装，必须先安装GraphicsMagick开发库（非ImageMagick），再通过phpenv指定php-config路径配置编译，最后在php.ini中用绝对路径加载gmagick.so。
phpEnv 本身不提供 gmagick 扩展的自动安装能力，它只是一个 PHP 多版本管理工具（类似 pyenv），不内置扩展编译逻辑。你要装 gmagick，必须手动处理依赖和编译流程——这点和 imagick 类似，但更冷门、更易卡在头文件或库链接上。
gmagick 编译前必须装对 GraphicsMagick
gmagick 是 PHP 对 GraphicsMagick 的封装，不是 ImageMagick 的别名。很多人混淆这两者，结果装完 ImageMagick-devel 还是报错。
Ubuntu/Debian：
sudo apt install graphicsmagick libgraphicsmagick1-dev
注意不是libmagickwand-dev（那是 ImageMagick 的）CentOS/RHEL：
sudo yum install GraphicsMagick-devel（EPEL 源需提前启用）
或用 dnf：sudo dnf install GraphicsMagick-develmacOS（Homebrew）：
brew install graphicsmagick
验证是否装好头文件：ls /usr/include/GraphicsMagick/magick/api.h（路径因系统而异，但必须存在）
立即学习“PHP免费学习笔记（深入）”；
如果找不到，说明开发包没装全，phpize 后运行 ./configure 会直接失败：checking for GraphicsMagick library... not foundconfigure: error: Cannot find GraphicsMagick library
pecl install gmagick 常见失败原因
pecl install gmagick 看似简单，但在 phpEnv 环境下容易出问题，因为：
-
pecl默认调用的是系统全局 PHP，不是你当前phpEnv切换的版本 - 它不会自动识别你用
phpEnv安装的 PHP 的php-config路径 - 如果你用
phpEnv装的是非标准路径（比如~/.phpenv/versions/8.2.10），pecl很可能找不到对应头文件
推荐改用手动编译：
# 先切到你要装扩展的 PHP 版本 phpenv local 8.2.10 # 下载源码（以 2.0.5rc1 为例） wget https://pecl.php.net/get/gmagick-2.0.5RC1.tgz tar xzf gmagick-2.0.5RC1.tgz cd gmagick-2.0.5RC1 # 关键：显式指定 php-config 路径（这是 phpEnv 安装的） ~/.phpenv/versions/8.2.10/bin/phpize ./configure --with-php-config=~/.phpenv/versions/8.2.10/bin/php-config make && make install
成功后会输出类似：Installing '/home/user/.phpenv/versions/8.2.10/lib/php/extensions/no-debug-zts-20220829/gmagick.so'
php.ini 配置和加载验证
gmagick 不支持 extension=gmagick 这种简写，必须写完整路径或确保 extension_dir 正确：
查看当前 PHP 的扩展目录：
php -i | grep extension_dir在
php.ini中添加（注意路径与上面make install输出一致）：extension=/home/user/.phpenv/versions/8.2.10/lib/php/extensions/no-debug-zts-20220829/gmagick.so重启 PHP 进程（如 php-fpm）或 Web 服务后验证：
php -m | grep gmagick
或运行：php -r "new Gmagick(); echo 'ok';"
如果报 Class 'Gmagick' not found，大概率是：
-
gmagick.so路径写错 -
GraphicsMagick运行时库没被找到（ldd检查gmagick.so依赖） - PHP 是 NTS 版本，却用了 TS 编译的
gmagick（极少见，但phpenv编译时若未指定--disable-zts可能触发）
gmagick 的实际使用门槛比 imagick 高，不仅因为文档少、社区支持弱，更因为它对底层库版本更敏感——比如 GraphicsMagick 1.3.38+ 才完全支持 WebP 写入，旧版即使扩展加载成功，调用 Gmagick::writeimage() 也可能静默失败。动手前先确认 gmagick -version 和 php --ri gmagick 输出的版本兼容性。
