<p>Composer 通过 config.platform 伪装目标平台环境以影响依赖解析：设置 config.platform.php 和 config.platform.ext-* 可覆盖真实 PHP 版本与扩展状态，仅作用于 install/update 阶段，不改变运行时行为。</p>
composer install 时如何让依赖包按目标平台编译扩展
Composer 本身不编译扩展，但能通过 platform 配置“伪装”当前 PHP 环境，影响依赖解析结果——尤其对含 ext-* 或 php 版本约束的包（如 ext-gd、php >= 8.2）。这在 CI/CD 构建多环境镜像或本地开发模拟生产环境时很关键。
核心是告诉 Composer：“我最终要部署到这个平台”，而非“我现在装在什么平台”。否则可能漏装、误装或跳过平台特定包。
-
config.platform.php会覆盖当前真实 PHP 版本，影响所有php约束判断 -
config.platform.ext-*（如ext-gd、ext-redis）会声明“该扩展已存在”，绕过扩展检测逻辑 - 这些配置只在
composer install和composer update时生效，不影响运行时 - 必须写在
composer.json的config字段下，不是全局配置
config.platform 配置写法与常见错误
错误写法比正确写法更常见：比如把 platform 写成顶层字段、用字符串代替对象、拼错扩展名。以下是最小可用结构：
{
"require": {
"ext-gd": "*",
"php": "^8.1"
},
"config": {
"platform": {
"php": "8.1.28",
"ext-gd": "1.0.0",
"ext-mbstring": "8.1.28"
}
}
}
注意点：
-
config.platform必须是对象，不能是数组或字符串 - 扩展名必须带
ext-前缀，gd❌，ext-gd✅ - 值可以是任意非空字符串（如
"1"、"present"），Composer 只检查是否存在，不校验版本 - 如果同时设了
config.platform.php和真实 PHP 版本不一致，composer show php显示的是伪装值
CI 场景下多平台构建的典型用法
一个项目需同时支持 PHP 8.1（Alpine）和 PHP 8.2（Ubuntu），但开发者本地是 PHP 8.3。靠 platform 可避免每次切环境重跑 composer update。
推荐做法：为不同平台维护独立 composer.json 分支或使用 composer config 动态写入：
# 构建 PHP 8.1 Alpine 镜像前 composer config platform.php 8.1.28 composer config platform.ext-gd 1 composer config platform.ext-openssl 1 composer install --no-dev --optimize-autoloader
关键细节：
-
composer config platform.xxx yyy会直接写入composer.json，适合脚本化流程 -
--ignore-platform-reqs是粗暴跳过所有平台检查，但会丢失扩展兼容性保障；platform是精准控制，更安全 - 若依赖中用了
ext-sodium但目标系统未启用，仅靠platform无法让运行时报错提前暴露——它只管安装，不管运行
为什么 vendor/autoload.php 加载后 ext-* 检查仍失败
这是最常被误解的一点：config.platform 只影响依赖解析和安装阶段，**完全不改变运行时行为**。如果你在代码里写了 extension_loaded('gd')，它依然取决于实际加载的扩展，和 composer.json 里怎么配无关。
所以：
- 安装时靠
platform解决“能不能装”，运行时靠容器/Dockerfile 确保“有没有装” - CI 中建议在
composer install后加一步验证：如php -m | grep gd - 某些包（如
league/flysystem-aws-s3-v3）会在require时触发扩展检测，这时platform无用，必须真实存在扩展
平台伪装不是魔法，它只解决 Composer 自己的依赖图计算问题。真实环境缺失扩展，运行时照样报错。
