Composer如何处理扩展依赖_Composer ext声明配置方式【核心】

Composer如何处理扩展依赖：一份关于ext声明的实战指南

先明确一个核心事实：Composer本身并不会为你安装任何PHP扩展。它的角色更像是一个严格的“环境检查员”，只在执行 composer install 或 composer update 命令时，调用 extension_loaded() 函数进行实时校验。一旦发现某个声明的扩展缺失，它会立刻报错并中断流程，连 vendor/autoload.php 文件都不会生成。所以，别指望它能帮你装扩展，它的任务是确保你的环境“配齐了家伙事儿”。

ext-xxx 声明必须和 `php -m` 输出完全一致

这听起来像是句废话，但拼写错误恰恰是部署失败最常见的原因，没有之一。Composer对扩展名的匹配是“死心眼”的，区分大小写，且必须和 php -m 命令输出的模块名一字不差。什么后缀、变体、别名，统统不认。

• ext-pdo_mysql ✅（标准答案，因为 php -m 输出就是 pdo_mysql）
• ext-pdo-mysql ❌（用了连字符？抱歉，查无此扩展）
• ext-gd ✅（记住，是 gd，不是 gd2、php-gd 或 gd.so）
• ext-intl ✅（同理，是 intl，不是 intl.so，也不是 ICU）

拿不准的时候，最稳妥的办法就是在本地环境执行 php -m | grep -i 扩展名，把确切的模块名“复制-粘贴”到 composer.json 的 require 字段里。

版本号只能写 `*` 或留空，`^5.3` 这类写法无效

这里有个关键认知需要扭转：PHP扩展本身并不遵循像库文件那样的语义化版本体系。因此，Composer对 ext- 包的“版本约束”，其真实作用仅仅是匹配“该扩展是否被加载”，它根本不会去解析扩展的实际版本号。

• "ext-redis": "*" ✅ 合法且最推荐，意思就是“我需要redis扩展，版本不限”。
• "ext-redis": "^5.3" ❌ Composer会直接忽略 ^5.3 这部分，但它会误导你的协作者，让他们误以为存在版本控制。
• "ext-json": "" ✅ 留空等价于 "*"，写法更简洁。

当然也有例外情况。比如 ext-intl 扩展，其功能实际依赖于底层的ICU库版本。但问题是，Composer无法感知这个层面。要确保功能正常，还得靠部署后的健康检查脚本，去验证 intl_get_icu_version() 这类函数返回的版本是否满足要求。

没配 `config.platform`，`ext-*` 就可能失效

你是否遇到过这种诡异情况：require 里明明写了 ext-curl，CI构建流水线一切正常，可代码一上线就报 Call to undefined function curl_init()？这大概率是漏掉了 config.platform 配置。

• 假设你的本地开发机是PHP 8.2，并且装全了所有扩展。但生产环境用的是精简版的PHP 8.1。如果没有设置 config.platform.php，Composer就会按照你本地的环境（PHP 8.2）来解析依赖，从而跳过了对目标环境（PHP 8.1）扩展集的校验。
• 另外要注意，config.platform 下面不应该直接写 ext-curl 这样的条目。如果你错误地写了 "ext-curl": "0"，就等于向Composer伪造了一个“curl扩展版本为0”的环境，它会直接跳过真实的扩展检查。
• 正确的做法是，只在 config.platform 中声明PHP版本本身，例如 "php": "8.1.0"。这样，Composer会基于这个版本来推导“哪些扩展理论上应该可用”，然后再结合 require 里声明的 ext-* 条目，在目标机器上进行真实的加载校验。

简单来说，require 定义了“我需要什么”，而 config.platform.php 定义了“我要在哪里运行”。两者结合，才能构成完整、准确的环境约束。

声明了 ext-* 不代表功能完整，运行时仍可能崩

最后，必须警惕一个更深层的陷阱：extension_loaded('openssl') 返回 true，仅仅意味着扩展模块被加载到了PHP进程中，绝不等于其所有功能都100%可用。OpenSSL底层库版本太旧、某些加密算法被禁用、甚至是SELinux等安全模块的限制，都可能导致函数在运行时静默失败。

• ext-pdo 存在 ≠ pdo_mysql 驱动可用。你必须单独声明 "ext-pdo_mysql": "*"。
• ext-gd 存在 ≠ 支持WebP图片处理。这取决于编译GD时是否链接了 libwebp 库。
• 对于关键功能路径，建议在代码中补充运行时检测，例如：function_exists('curl_init') && extension_loaded('mbstring')。

还有一个极其容易被忽略的“坑”：在Docker构建过程中，你执行了 apt install php-curl 并且显示成功，但如果安装后没有重启PHP-FPM进程，那么 extension_loaded('curl') 仍然会返回 false。此时，composer install 会如实报错。请务必正视这个错误，不要试图绕过它，因为它真实地反映了运行时环境的缺失。