PECL安装Redis失败时，先检查三件事：一是确认pecl命令是否存在（which pecl或php -m | grep pear）；二是验证phpize是否可用，缺失则需安装php-dev或php-devel；三是排查系统依赖库如libzip-dev是否已安装。

pecl install 命令失败时，先检查这三件事

直接运行 pecl install redis 报错，大概率不是扩展本身的问题，而是环境没对齐。常见卡点有：

• pecl 命令根本不存在 → 先确认 PHP 是否带 PEAR/PECL：运行 which pecl 或 php -m | grep pear；若无，需先用 php go-pear.php 安装 PEAR 环境
• 报 phpize not found → 说明系统缺少 PHP 开发头文件，Ubuntu/Debian 要装 php-dev，CentOS/RHEL 是 php-devel
• 编译阶段提示 libzip not found 类错误 → 不是 PECL 的锅，是扩展依赖的系统库没装，得先 apt install libzip-dev（或对应系统的包名）

手动编译安装时，--with-php-config 参数不能省

很多人跳过这步，直接 ./configure，结果生成的 .so 文件加载时报 undefined symbol: php_json_decode_ex 这类符号错误。原因很直接：扩展编译时链接了错误版本的 PHP API。

必须显式指定路径，例如：

./configure --with-php-config=/usr/local/php/bin/php-config

验证是否生效：执行后看输出里有没有 Build complete 和 Installing shared extensions，同时注意末尾显示的安装路径是否和 php -i | grep extension_dir 一致。不一致就得手动拷贝或改 php.ini 中的 extension_dir。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

立即学习“PHP免费学习笔记（深入）”；

extension=xxx.so 加载失败的典型表现和定位方法

写进 php.ini 后重启 php-fpm 或 Apache，但 php -m | grep xxx 没输出，常见原因有：

• extension=redis.so 写成了 extension=redis（漏了 .so）或路径写死成绝对路径（如 extension=/usr/lib/php/.../redis.so），后者在 PHP 升级后极易失效
• 扩展已加载但被禁用：检查是否有 disable_functions 或 extension=xxx.so 被注释掉，或被其他配置文件（如 zzz-custom.ini）覆盖
• PHP 是 NTS 版本，却用了 TS 编译的 .so（Windows 下尤其常见）→ 查 php -v 输出末尾是否含 NTS，再核对 DLL 名称里是否含 ts（如 php_redis.dll vs php_redis_nts.dll）

macOS 和 Linux 的编译差异容易被忽略

macOS 默认用 libtool 和 clang，某些扩展（如 yaml、igbinary）在 configure 阶段会因 -fno-common 报错。解决方式不是换 GCC，而是加参数：

./configure --with-php-config=/opt/homebrew/bin/php-config CFLAGS="-fcommon"

另外 macOS 上 extension_dir 默认路径常为 /opt/homebrew/lib/php/.../，而非 Linux 常见的 /usr/lib/php/.../，硬编码路径在这里几乎必挂。最稳妥的做法是：编译完看 make install 输出的路径，再用 php -i | grep extension_dir 对照，只写 extension=redis.so，别写全路径。