PECL扩展不能通过composer require安装，需手动用pecl install或系统包管理器安装并配置php.ini；composer仅校验扩展是否存在及版本是否匹配，platform配置仅用于依赖解析阶段伪装扩展存在，不解决运行时缺失问题。
PECL扩展不能直接通过 composer require 安装
Composer 本身不编译、不安装任何 PHP 扩展，它只管理 PHP 类库（即纯 PHP 代码或已编译好的二进制扩展）。当你在 composer.json 中写 "ext-redis": "*" 或 "ext-mongodb": "^1.15"，Composer 只做运行时检查：安装前验证当前 PHP 是否已加载该扩展、版本是否满足；不满足就报错 ext-mongodb not found 或 ext-redis has wrong version。
真正安装 PECL 扩展需手动操作：
- 用
pecl install mongodb编译安装（需系统有phpize、gcc、make等） - 或通过系统包管理器（如
apt install php-mongodb、brew install php-mongodb）获取预编译版本 - 确认扩展已写入
php.ini（如extension=mongodb.so），并重启 PHP 进程（CLI/FPM）
platform 配置只能“假装”扩展存在，不能绕过真实依赖
有些项目想在 CI 或无 root 权限环境跳过扩展检查，会误用 "platform"：
{
"config": {
"platform": {
"ext-igbinary": "3.2.1",
"ext-msgpack": "2.1.2"
}
}
}
这仅让 Composer 在依赖解析阶段认为这些扩展“已存在”，但不会启用它们。运行时若扩展未真实加载，仍会抛出 Class not found 或 Call to undefined function。常见误用场景：
立即学习“PHP免费学习笔记（深入）”；
- 本地开发机没装
ext-swoole，靠platform强行composer install成功 → 部署后一跑就崩 - GitHub Actions 中设
platform掩盖缺失扩展 → 测试通过但实际逻辑不可用 -
platform版本号写错（如写成"ext-openssl": "1.0.0"）→ Composer 不报错，但运行时因函数签名不匹配崩溃
如何正确声明和验证扩展依赖？
在 composer.json 的 require 中声明扩展，是唯一受支持的声明方式。Composer 会自动检查 PHP_VERSION、ext-*、lib-* （如 lib-curl）三类平台约束。
推荐写法：
{
"require": {
"php": ">=8.1",
"ext-json": "*",
"ext-mbstring": "*",
"ext-redis": "^5.3.7",
"ext-sodium": "*"
}
}
注意要点：
- 版本约束对扩展有效（如
"^5.3.7"对应redis扩展 5.3.7+），但需扩展自身支持PHP_VERSION_ID兼容性标注 -
"*"表示“任意已加载版本”，不等于“可选”——缺失仍会中断安装 - CI 中应真实安装扩展（如 GitHub Actions 使用
shivammathur/setup-phpaction），而非依赖platform
Docker 和部署时最容易忽略的点
很多团队在 Dockerfile 中漏掉扩展编译步骤，或错误地把 pecl install 放在 composer install 之后：
-
pecl install必须在composer install前执行，否则composer install会因扩展缺失失败 -
docker-php-ext-install（如docker-php-ext-install pdo_mysql）比pecl更稳定，优先用它装官方扩展 - 自定义
.so文件路径需与php -i | grep 'extension_dir'输出一致，否则extension=xxx.so加载失败 - Alpine 镜像需额外安装
php*-dev和build-base，否则pecl编译直接报phpize not found
扩展不是 Composer 的责任边界，它的角色只是“校验者”而非“安装器”。把编译、配置、加载全链路理清楚，比调通一条 composer require 命令重要得多。
