Composer怎么处理ext扩展的依赖声明_Composer扩展依赖声明规范【核心】

Composer 压根不会帮你装 PHP 扩展，它只会在 composer install 或 composer update 时检查那些扩展是否已经在系统里启用了。如果缺了，直接报错中断，连 autoload 文件都不生成。所以，别指望 Composer 能当扩展管理器，它只是一个“检查员”。

ext-xxx 必须写在 require 或 require-dev 里

这不是什么插件或隐藏约定，而是 Composer 原生支持的伪包名机制。它只认 ext-xxx 这种格式，并且必须放在 composer.json 的 require（生产环境必不可少）或 require-dev（仅开发阶段）字段里，否则 Composer 根本不会去理会。

• "ext-curl": "*" 合法，但 "ext-curl": "^7.4" 没意义——版本号在这里不指向 cURL 库的版本，只表示“存在即可”。
• "ext-mbstring": "" 和 "ext-mbstring": "*" 等价，都是“只要有就行”。
• "ext-intl": "^1.0" 这种写法虽然能解析，但实际校验时依然只调用 extension_loaded('intl')，版本约束形同虚设。
• 扩展名必须和 php -m 输出的完全一致：小写、无下划线、无后缀。比如 pdo_mysql，不能写 pdo-mysql 或 php-pdo-mysql。

报错信息明确，但容易误判为“Composer 没装好”

运行 composer install 时如果缺失扩展，你会看到类似这样的错误：

- Root package 'my/project' requires ext-gd (*), but it is not present.

这不是 Composer 自身的问题，而是环境没配好。常见的混淆点有几个：

• 有人以为 composer require ext-gd 能直接装上扩展——不行，Composer 没这个能力。
• 看到 ext-json 报错，却去搜“如何用 Composer 安装 json”——其实 PHP 8+ 已经内置了 json，只需确认 php.ini 中没有注释掉 extension=json 即可。
• Docker 构建时先跑 composer install 再装扩展——顺序反了。必须先 RUN docker-php-ext-enable gd 或 apk add php82-gd，再执行 Composer，否则扩展还没装，Composer 自然报错。

config.platform.ext-xxx 是“假装存在”，不是绕过检查

这个配置的作用不是跳过校验，而是让 Composer 在依赖解析阶段“按目标环境模拟可用扩展”。举个例子：

"config": {
    "platform": {
        "ext-igbinary": "3.2.14",
        "php": "8.1.28"
    }
}

它的实际效果是：

• 告诉 Composer：“假设当前环境有 ext-igbinary 3.2.14”，从而影响哪些包会被选入 composer.lock。
• 如果真实环境没有该扩展，composer install 仍然会失败——platform 并不会压制运行时的校验。
• 适合 CI 场景：比如本地 PHP 8.3 装了 xdebug，但生产环境没有，又不想让 xdebug 相关包混进 lock 文件，就可以用 "ext-xdebug": "0" 模拟“不存在”。

真正容易被忽略的是：声明了 ext-* 之后，你得确保部署流程里包含扩展安装/启用的步骤。否则，composer install 虽然成功了，但 php artisan serve 或 index.php 一跑就报 Call to undefined function curl_init()——那说明校验环节根本没触发，大概率是漏写了 ext-curl 声明，或者用了 --ignore-platform-reqs 却没意识到后果。