如何在Composer中指定PHP的特定扩展需求
composer.json 里怎么声明必须启用的 PHP 扩展
很多开发者可能没注意到，Composer本身并不会主动去检查你的PHP环境里启用了哪些扩展。不过，它提供了一个非常直接的约束机制：在composer.json文件的require字段里，通过ext-xxx这样的条目来声明硬性依赖。这个声明可不是摆设，它会直接决定你的composer install或composer update命令能否顺利执行。
举个例子，如果你的项目必须用到cURL功能，那么composer.json里就必须明确写上：
{
"require": {
"ext-curl": "*"
}
}
这里的*代表“任意版本”——因为PHP扩展本身并不遵循语义化版本规则。Composer的校验逻辑很简单：它只会去检查php -m命令的输出列表里，是否存在这个扩展名。
有几点细节需要特别注意：
- 其他扩展如
ext-mbstring、ext-openssl、ext-pdo_mysql，声明方式完全一样。 - 扩展名大小写敏感：写成
ext-PDO会导致校验失败，正确的写法是ext-pdo。 - 对于Windows用户，虽然扩展文件可能带有
.dll后缀（比如php_curl.dll），但Composer只认扩展的核心名称部分，所以依然要写ext-curl。
为什么 composer install 不报错，但运行时却提示扩展缺失
这个问题堪称经典陷阱。其根源往往在于：你本地机器上，命令行（CLI）的PHP和Web服务器（比如Apache或Nginx）所用的PHP，根本不是同一个配置。结果就是，在命令行下php -m显示扩展已加载，Composer校验通过，但实际跑应用的Web环境却压根没启用这个扩展。
验证方法其实很直观：
- CLI环境：直接运行
php -m | grep curl。 - Web环境：创建一个
info.php文件，内容就是，然后在浏览器里访问它，搜索“curl”关键字。
如果两者结果不一致，那就证实了配置是分离的。Composer安装时检查的是CLI的PHP，而你的应用运行时用的是另一套。于是，即便composer install大功告成，代码里一旦执行到new CurlHandle()或者curl_init()，立刻就会抛出“Class not found”或“undefined function”这类令人头疼的错误。
如何让 Composer 在 CI/CD 中更早暴露扩展问题
持续集成（CI）环境，比如GitHub Actions，为了追求轻量和速度，默认使用的PHP镜像往往是“最小化”安装，很多常用扩展都不包含。光靠在composer.json里声明依赖是不够的，必须在CI的流程步骤中，加入显式的扩展安装命令。
以GitHub Actions为例，你需要在steps里添加类似这样的环节：
- name: Install PHP extensions
run: |
sudo apt-get update
sudo apt-get install -y php-curl php-mbstring php-xml php-zip
sudo phpenmod curl mbstring xml zip
这里有几个关键点需要把握：
- 在Debian/Ubuntu系统上，软件包名称通常是
php-xxx，而不是php7.4-xxx（除非你明确锁定了某个PHP小版本）。 - 如果你用的是Alpine Linux镜像，那包名前缀又变了，得用
apk add php7-curl这样的命令。 phpenmod是Debian系特有的工具，用于启用模块。如果在CentOS/RHEL系统上，你可能需要手动创建配置文件，例如echo "extension=curl.so" > /etc/php/8.1/cli/conf.d/20-curl.ini。- 切记不要跳过
phpenmod或手动配置ini文件这一步，否则很可能导致PHP CLI和PHP-FPM的扩展状态不同步，埋下新的隐患。
ext-xxx 写错或漏写会导致什么后果
后果很直接：当其他开发者克隆你的项目后，composer install可能会顺利执行，但项目一运行就立刻崩溃。更麻烦的是，错误堆栈通常不会直接告诉你“缺少某个扩展”，而是会报一些下游的类或函数调用失败，排查起来非常耗时。
来看几个典型的“翻车”案例：
- 漏写
ext-json：代码调用json_encode()时，会报“Call to undefined function”。很多人第一反应是PHP版本太低，完全想不到是扩展依赖没声明。 - 误写成
ext-gd2：这个扩展名根本不存在（正确的应该是ext-gd）。Composer会直接忽略这条无效的条目，既不报错也不校验，等于白写。 - 写了
ext-imagick但没装底层库：如果系统没有安装ImageMagick开发库，PHP的imagick扩展就无法编译加载。php -m里自然没有它，Composer检查会失败。但错误信息通常只是笼统地提示“The requested PHP extension ext-imagick is missing from your system”，新手可能无法立刻意识到是系统级依赖缺失。
说到底，扩展名的拼写必须和php -m输出的结果一字不差。多一个字符、少一个连字符，都会让这条声明失效。最稳妥的做法是：先在目标部署环境中执行一遍php -m，然后把准确的扩展名复制粘贴到composer.json里。
