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

## 关于 Composer 如何管理 PHP 扩展依赖这件事 说实话，很多 PHP 开发者第一次遇到 Composer 报 `ext-xxx not found` 时都会懵一下——Composer 不是包管理器吗？怎么还管起扩展了？但它的逻辑其实很简单：**Composer 本身不安装、不编译任何 PHP 扩展，它只在校验环节检查 `ext-*` 是否已加载并且版本匹配；如果声明错误或者环境缺失，它会直接在 `composer install` 阶段报错中断，绝不会等到运行时才抛出一个模糊的 `Call to undefined function`。** 这一点很重要，把它理解成“运行契约”更合适——你写进 `require` 里的每一个 `ext-xxx`，都是在告诉所有部署节点：必须提前准备好这个扩展。否则，线上可能连错误堆栈都看不清，只会出现 `Class 'Imagick' not found` 或者 `imagecreatefrompng(): Failed to load` 这种让人抓狂的异常。

Composer 本身不安装、不编译任何 PHP 扩展，它只校验 ext-* 是否已加载且版本匹配；声明错误或环境缺失，会在 composer install 阶段直接报错中断，而不是等到运行时报 Call to undefined function。

### ext-* 必须写在 require 或 require-dev 里，不能放其他字段 不少开发者容易把 `config.platform` 当成声明扩展的地方——其实完全不是。`config.platform` 是干嘛用的？它只是一个“假装扩展存在”的临时绕过手段，用于本地开发或测试环境临时跳过检查，不是正向声明。真正起约束作用、能触发 Composer 校验逻辑的地方，只有 `require` 和 `require-dev` 下的 `ext-xxx` 条目。 写的时候有几个容易踩的坑： - **大小写与命名**：`ext-curl`、`ext-pdo_mysql`、`ext-mbstring` 这些必须全小写，并且与 `php -m` 命令输出的名称完全一致（不含下划线、不带任何版本后缀）。比如 `ext-MySQL` 就是错的，Composer 不会报错，但它也不会校验你实际装了没。 - **版本号写法有限制**：版本号只支持三种形式——`"*"`（通配，任意版本可用）、`""`（等价于通配）、或者严格的语义化版本，如 `"^1.4"`、`">=1.0"`。但注意：像 `"^7.4"` 或 `"1.0.0"` 这种写法是无效的——Composer 不会提示你写错了，但会静默忽略版本约束，直接当作 `"*"` 处理。回头线上如果因为扩展版本不兼容出了问题，查起来相当痛苦。 - **开发专用扩展要放对地方**：比如 `ext-xdebug`、`ext-swoole_test_helper` 这类只在开发调试时需要的扩展，应该放进 `require-dev` 而不是 `require`。否则当你在 CI 或生产环境执行 `composer install --no-dev` 时，Composer 依然会因为找不到这些扩展而直接中止安装——哪怕它们压根不该出现在生产环境里。 ### ext-* 校验发生在 install/update 时，不等于运行时可用 Composer 的校验机制是什么呢？它只是在执行 `composer install` 或 `composer update` 的时候，调用 `extension_loaded('curl')` 检查扩展是否已加载，再用 `phpversion('curl')` 看看版本号是否满足约束。但它不会去验证： - 扩展是否被正确启用（比如 php.ini 里虽然加载了，但被注释掉了 `extension=curl.so`） - 扩展的函数签名是否与代码兼容 所以实际部署中常见的翻车场景包括： - **Docker 构建顺序问题**：很多人在 Dockerfile 里先跑 `composer install`，再安装扩展（比如 `apt install php-curl` 或 `docker-php-ext-install curl`）——结果 `composer install` 阶段直接报 `ext-curl not found`。正确的顺序是：先把扩展装好（确保已加载），再执行 Composer 命令。 - **Windows 环境配置**：Windows 用户需要确认 `php.ini` 里已经取消注释对应行（比如 `extension=php_curl.dll`），并且对应的 DLL 文件确实存在于 `ext/` 目录下。缺少任何一个环节，Composer 都会报错。 - **`config.platform` 的迷惑性**：有些人为了在本地开发时跳过扩展检查，会在 `config.platform` 里设置 `"ext-redis": "5.3.7"`。这样 `composer install` 确实能通过，但实际运行时如果没装 `redis.so`，`new Redis()` 会直接抛出 `Class 'Redis' not found`——Composer 帮不了你，因为你骗它说扩展已经在了。 ### 某些扩展的版本号根本不可靠，约束要谨慎 这一点是最容易被忽略的，也是很多项目“本地正常、CI 就挂”的根源之一。 像 `ext-json`、`ext-pcre` 这类 PHP 内置扩展，它们的版本号并不会随着 PHP 小版本升级而更新。`phpversion('json')` 通常返回一个固定字符串，比如 `"1.4.0"`，几年都不变。如果你在 `require` 里硬写 `"^1.5"`，本地开发环境可能恰好满足（因为你的 PHP 版本恰好带这个版本），但换一台机器、换一个 PHP 小版本，可能就变成 1.3.x 了，导致 `composer install` 直接报错，而实际上 `json` 扩展本身完全可用。 所以建议优先用 `"*"`，除非你明确依赖某个特定函数——比如 PHP 8.1 才引入的 `json_validate()`，它要求 json 扩展版本 >= 1.6，这时候才需要写版本约束。 另一个典型的坑是 `ext-openssl`。它的版本号不是 PHP 自己定的，而是来自底层的 OpenSSL 库。`phpversion('openssl')` 可能返回类似 `"101010cf"` 这样的十六进制字符串——这玩意儿和语义化版本完全不兼容，你写 `"^1.0"` 根本匹配不上。所以对于这类扩展，用 `"*"` 是最稳妥的，除非你确切知道目标环境里底层库的版本。 不确定的情况下，最好在执行 Composer 的目标环境（比如 CI 的 Runner、容器镜像、serverless 函数运行时）上先跑一句： ```bash php -r "var_dump(extension_loaded('xxx')); var_dump(phpversion('xxx'));" ``` 看看实际输出，再据此决定到底要不要写版本约束、写什么值。 最后再强调一次：扩展声明不是“可有可无的文档注释”，而是项目运行契约。一旦写进 `require`，就意味着所有部署节点——包括 CI runner、容器镜像、甚至 serverless 函数的底层 runtime——都必须满足这个条件。漏掉一个 `ext-gd`，线上图片处理功能直接哑火；而错误堆栈里不会告诉你缺了扩展，只会抛出模糊的 `imagecreatefrompng(): Failed to load` 或 `Class 'Imagick' not found`。尽早把扩展依赖写清楚，反而是最省心的做法。