Composer如何处理扩展依赖的ext声明配置方式是什么？

本文共计893个文字，预计阅读时间需要4分钟。

markdownComposer 无法安装任何 PHP 扩展，只有在执行 composer install 或 composer update 时调用 extension_loaded() 进行实时校验；缺失则报错中断，不会生成 vendor/autoload.php。

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

拼写错误是部署失败最常见原因。扩展名区分大小写、不能带后缀、不能加空格或下划线变体：

• ext-pdo_mysql ✅（php -m 输出就是 pdo_mysql）
• ext-pdo-mysql ❌（连不上，Composer 查不到）
• ext-gd ✅（不是 gd2、php-gd 或 gd.so）
• ext-intl ✅（不是 intl.so，也不是 ICU）

不确定时，本地执行 php -m | grep -i gd 确认真实模块名，再照抄进 composer.json 的 require 字段。

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

PHP 扩展本身没有语义化版本体系，Composer 对 ext- 包的版本约束仅用于匹配“是否加载”，不解析实际版本号：

• "ext-redis": "*" ✅ 合法且推荐
• "ext-redis": "^5.3" ❌ Composer 会忽略版本部分，但容易误导协作者以为有版本控制
• "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 就按本地环境解析依赖，跳过对目标环境扩展集的校验
• config.platform 下不该写 ext-curl，否则等于伪造环境："ext-curl": "0" 会让 Composer 直接跳过真实检查
• 正确做法是只声明 config.platform.php 版本，让 Composer 自动推导该版本下哪些扩展“理论上可用”，再结合 require 中的 ext-* 做真实加载校验

也就是说：require 定“要什么”，config.platform.php 定“在哪跑”，两者合起来才构成完整约束。

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

extension_loaded('openssl') 返回 true，不代表 openssl_encrypt() 一定可用——OpenSSL 库版本太旧、加密算法被禁用、甚至 SELinux 限制都可能导致静默失败：

• ext-pdo 存在 ≠ pdo_mysql 可用，必须单独声明 "ext-pdo_mysql": "*"
• ext-gd 存在 ≠ 支持 WebP，得看编译时是否链接 libwebp
• 关键路径建议补运行时检测：function_exists('curl_init') && extension_loaded('mbstring')

最容易被忽略的是：Docker 构建中 apt install php-curl 成功，但没重启 PHP-FPM 进程，extension_loaded() 仍返回 false —— 此时 composer install 会如实报错，别绕过。