通过 Composer 安装带有 C 扩展依赖的 PHP 库实战

搞 PHP 开发的，多少都跟 Composer 打过交道。但很多时候，看似是 Composer 在报错，其实根源根本不在它身上。最近有个朋友就遇到了一台服务器拉 Lara vel 项目，composer require 直接挂了，提示找不到 ext-redis。一看这个报错，别慌，先搞清楚问题在哪一层。

composer require 报错 ext-redis 未找到？这锅 Composer 不背

Composer 本身不负责装 C 扩展，它只管检查这个扩展在不在。当你执行 composer require predis/predis 或者 composer require illuminate/redis 时，如果项目的 composer.json 里声明了 "ext-redis": "*"（这在 Lara vel 10+ 或某些包的依赖里很常见），而你的 PHP 环境压根没启用 redis 扩展，Composer 就会毫不犹豫地抛出一个错误：Package ext-redis is required and cannot be found。

这个问题的本质不是依赖写错了，也不是网络不通，而是底层的 PHP 环境缺了东西。这时候 composer require 会直接终止，连 vendor/ 文件夹都不会生成。

• 怎么确认？很简单，先跑一下 php -m | grep redis，如果没有任何输出，基本就坐实了——扩展没加载。
• 别急着重装 PHP 或者删 vendor，先确认扩展本身到底装没装，只是没启用。
• 再看一下 php --ini 输出的配置文件路径，打开对应的 php.ini，看看里面有没有 extension=redis.so（Linux/macOS）或 extension=php_redis.dll（Windows）。

Ubuntu/Debian 上装 redis.so，用 apt 最省心

系统级的 C 扩展，优先用包管理器安装。这一步能省掉配置编译环境、准备头文件、匹配 PHP 开发版本等一系列麻烦。Ubuntu 22.04+ 和 Debian 12+ 上，扩展已经按 PHP 版本分好了包。比如 PHP 8.3，就要装 php8.3-redis，而不是笼统的 php-redis。

操作前先确认当前命令行使用的 PHP 版本：php -v。然后选对应的包来装：

• sudo apt update
• sudo apt install php8.3-redis（记得替换成你实际的 PHP 主版本号）
• 装完之后一般不需要手动修改 php.ini，apt 会自动在 /etc/php/8.3/cli/conf.d/redis.ini 里写上一行 extension=redis.so。
• 验证方法：php -m | grep redis 应该能看到输出；想确认具体版本可以用 php -i | grep "redis version"。

pecl install redis：没 apt 包时的备选方案

CentOS Stream、Rocky Linux、Alpine，或者 PHP 是自编译的场景下，pecl install 可以顶上。但这个路子对编译环境要求很高——必须有完整的编译工具链和 PHP 头文件（php-devel 或 php-dev）。漏掉任何一个依赖，就会卡在 configure: error: Cannot find php-config 或者 make: *** [Makefile:193: redis.lo] Error 1 这种错误上。

以 Alpine 为例（Docker 环境下常见）：

• apk add php83-dev autoconf automake g++ make（注意 PHP 版本后缀要匹配）
• pecl install redis
• 安装完成后，需要手动把 extension=redis.so 加到 php.ini 里。Alpine 默认可能没有现成的 ini 文件，通常可以通过 echo "extension=redis.so" > /etc/php83/conf.d/redis.ini 来生成。
• 注意：修改配置文件后，需要重启 PHP-FPM 或 Web 服务才能生效。CLI 模式可能立即可用，但 Web 请求走的还是旧进程。

C 扩展装好后，composer require 才能真正开工

C 扩展启用之后，composer require 不会自动重试刚才失败的那一步。需要重新执行一次命令。但这里有几个细节：

• 确认当前 shell 的 php 命令指向的是你要用的 PHP 版本。比如 /usr/bin/php8.3 而不是 /usr/bin/php，否则 Composer 可能用错了 CLI 环境。
• 如果项目的 composer.json 里配了 platform 参数（比如 "config": {"platform": {"php": "8.2.0"}}），而你装的却是 8.3 的扩展，Composer 仍然会报错——它按照配置模拟环境，不读真实的 PHP 版本。
• 装完扩展后第一次跑 composer require，仍然可能遇到 autoload 冲突导致的 Class not found 错误。这时候跑一下 composer dump-autoload 刷新映射关系，问题通常就解决了。尤其是当你修改过 composer.json 的 autoload 段，或者引入了包含自定义 autoloader 的包时，这个步骤必不可少。

C 扩展和 Composer 是两件完全不同的事：一层在 PHP 解释器里，一层在 PHP 代码里。很多人卡在中间，以为是 Composer 的问题，折腾了半天才发现，不过是 php.ini 里少了一行，或者 php -m 的输出没刷新过来。