在Composer使用中强制执行PHP扩展检查以防止生产环境缺失关键模块

很多团队都踩过这样一个坑：本地开发环境跑得好好的项目，一部署到生产服务器就报错，错误信息往往是某个类没找到，比如Class 'Imagick' not found。定位到最后，多半是扩展没装。麻烦的是，composer install默认根本不检查扩展是否存在，它只管PHP版本对不对。换句话说，缺了扩展，Composer依然会笑嘻嘻地把依赖装好，然后错误留到运行时才炸。

其实Composer本身提供了一个内置的扩展校验机制，只是默认没开——它就是platform-check功能。

让Composer install在缺扩展时直接报错

关键一步：在composer.json的config段里显式打开这个开关：

"config": {
  "platform-check": true
}

开启之后，Composer在执行安装流程前，会主动调用extension_loaded()去检查所有require里声明的ext-*扩展是否存在。这里特别要留意的是：它只认ext-开头的条目，比如"ext-gd": "*"才有效果；你写成"gd": "*"是没用的。

另外还有个容易忽略的细节：PHP CLI和Web SAPI的扩展列表可能不一样。所以最稳妥的做法，是在目标环境——也就是生产服务器的CLI下运行composer install。本地没问题不代表线上也没问题。

运行时报错，其实不该怪autoloader

很多人会有一个错觉：既然vendor/autoload.php加载之后才报扩展缺失，那是不是autoloader没处理好？其实不是。autoloader只管类的自动加载，它不负责检查扩展是否就绪。真正该拦截的位置应该是在依赖解析阶段，而不是运行时。

所以，别指望用class_exists('Imagick', false)或function_exists()来做运行时兜底——那是补救，不是预防。更好的做法，是把扩展检查前移到CI/CD的构建环节。不过要注意，那种在composer install --no-dev后加一句php -m | grep gd的做法其实不可靠，因为php -m查到的是CLI模块，而线上Web请求跑的是另一个PHP实例。最稳妥的方案仍然是：开启platform-check + 在目标环境中执行composer install。

require-dev里的ext-*扩展，怎么处理？

如果require-dev里写了"ext-xdebug": "*"，而生产环境禁用了Xdebug，那platform-check就会报错。问题来了：删掉dev依赖吧，本地开发可能受影响；不删吧，生产部署又报错。

正确做法是搞清楚platform-check的工作范围。Composer 2.2以上版本，默认只检查require里的扩展。如果你升级过Composer，或者设置了COMPOSER_DEV_MODE=1，那可能会误触dev依赖。所以在生产部署时，务必加上--no-dev参数。这样require-dev就不会参与依赖解析，platform-check自然也就跳过了其中的ext-*条目。

顺便提一句：别把生产必需的扩展写在require-dev里，比如ext-opcache这类，就应该老老实实放在require中。

如果CI环境Composer版本太老，还有别的办法吗？

有些老旧CI环境里Composer版本太低（低于2.0.9），不支持platform-check，或者项目本身就锁定了旧版Composer。这种情况下，可以临时用一个小脚本做兜底检查：

php -r "$req = json_decode(file_get_contents('composer.json'), true)['require'] ?? [];
foreach ($req as $pkg => $ver) {
    if (strpos($pkg, 'ext-') === 0) {
        $ext = substr($pkg, 4);
        if (!extension_loaded($ext)) {
            echo "Missing PHP extension: $ext\n";
            exit(1);
        }
    }
}"

这个脚本的工作逻辑很简单：读取composer.json中的require段落，找出所有ext-开头的依赖，逐条调用extension_loaded()做存在性检查。注意它不处理版本约束，比如"ext-zip": "^1.2"这种写法，脚本只会判断扩展是否被加载，版本号被直接忽略。

当然，有些平台差异和扩展别名问题（比如mbstring在某些发行版叫php-mbstring），目前还没有全自动的完美解法，还是需要人工核对一下。