<p>Composer 通过 require 声明 ext-* 依赖并配合 config.platform 强制校验 PHP 扩展是否启用，防止运行时错误；platform 模拟目标环境以确保依赖解析准确，扩展名须与 php -m 输出完全一致（小写、下划线）。</p>
composer.json 里怎么声明 PHP 扩展依赖
Composer 不会自动检测或安装 PHP 扩展，但能通过 require 和 platform 配置强制校验扩展是否已启用。核心是让 composer install 或 composer update 在扩展缺失时直接报错，而不是等到运行时报 Class not found 或 Call to undefined function。
常见错误是只写 "ext-curl": "*" 却没配 config.platform，结果 CI 环境或新服务器上因 PHP 编译参数不同（比如没带 --with-curl）导致构建通过、运行失败。
-
"ext-mbstring": "*"表示必须启用mbstring扩展，版本号不重要（PHP 扩展无语义化版本） -
"ext-redis": "^5.3"是无效写法 —— 扩展版本号由 PHP 模块本身决定，Composer 只认*或留空 - 若项目依赖
ext-gd但只在 PNG 处理逻辑中用到，可考虑用class_exists('GdImage')运行时判断，而非强声明进composer.json
{
"require": {
"php": "^8.1",
"ext-curl": "*",
"ext-mbstring": "*",
"ext-openssl": "*",
"ext-json": "*",
"ext-pdo": "*",
"ext-pdo_mysql": "*"
},
"config": {
"platform": {
"php": "8.1.28"
}
}
}
为什么需要 config.platform.php
本地开发环境 PHP 是 8.2，但生产环境锁定为 8.1.28 —— 如果不设 config.platform.php，Composer 会按本地版本解析依赖，可能装入仅兼容 8.2 的包（比如用了 match 表达式但没加 #[\ReturnTypeWillChange]），或漏掉对旧版语法的兼容检查。
更关键的是：平台扩展也受 platform 影响。例如你本地有 ext-igbinary，但生产没有，又没在 require 中声明它，Composer 就不会报错。这时候必须靠 platform 显式“降级”声明可用扩展集，才能触发校验。
立即学习“PHP免费学习笔记（深入）”；
-
config.platform是模拟目标环境的“虚拟平台”，Composer 会据此判断哪些扩展/PHP 版本真正可用 - 它不影响实际运行时行为，只影响依赖解析和安装前检查
- CI 脚本中建议加上
composer install --no-dev --ignore-platform-reqs仅用于生成锁文件，但正式部署必须去掉--ignore-platform-reqs
扩展名大小写与拼写陷阱
PHP 扩展名区分大小写，且命名不统一：ext-pdo_mysql 不能写成 ext-pdo-mysql 或 ext-pdomysql；ext-iconv 在某些 Alpine 镜像中叫 ext-iconv，但 Windows 下可能是 php_iconv.dll 对应 ext-iconv —— Composer 只认 php -m 输出的模块名小写形式。
查准名字最可靠的方式是执行：
php -m | grep -i curl # 输出：curl # 所以写 "ext-curl": "*" <p>php --ri mbstring | head -1</p><h1>输出：mbstring</h1><h1>所以写 "ext-mbstring": "*"</h1>
-
ext-zip≠ext-zlib：前者操作 ZIP 文件，后者是压缩基础库，两者独立 -
ext-pdo_pgsql和ext-pdo_sqlite必须按实际数据库类型单独声明，ext-pdo本身只是接口层，不提供驱动 - Docker 用户注意：
docker-php-ext-install启用的扩展名，就是 Composer 要求的名称，比如docker-php-ext-install pdo pgsql后需声明"ext-pdo": "*", "ext-pdo_pgsql": "*"
运行时扩展检测比 composer.json 更灵活
composer.json 声明是静态约束，适合构建期卡点；但有些扩展（如 ext-apcu、ext-opcache）属于性能优化项，缺失不影响功能，只降速。这类更适合运行时检测 + 日志告警，而不是阻断安装。
例如 Laravel 的 AppServiceProvider::boot() 中可加：
if (!extension_loaded('apcu')) {
\Log::warning('APCu extension not loaded — cache performance may suffer');
}
- 扩展加载状态无法在
composer.json中做条件声明（比如“有 apcu 就用，没有就 fallback 到 file cache”） - 某些 SaaS 部署平台（如 Heroku、Laravel Vapor）限制扩展安装，硬声明会导致部署失败，此时应改用
function_exists()或extension_loaded()动态适配 -
ext-sodium在 PHP 7.2+ 已内置，但部分旧编译版本仍需手动启用，声明时仍应保留"ext-sodium": "*"保证一致性
扩展依赖不是越全越好，关键是匹配运行环境真实能力。漏声明会埋 runtime error，乱声明会让部署变脆弱。
