composer install 报 ext-xxx 缺失但实际已安装，是因平台依赖校验冲突；应先用 php -m 验证扩展名，再用 --ignore-platform-req=ext-gd 精确跳过，或配置 config.platform 模拟目标环境。
composer install 时提示 ext-xxx 缺失，但实际环境已安装
这是典型的平台依赖校验冲突：Composer 默认会检查当前 PHP 环境是否满足 composer.json 中声明的 platform 要求（比如 "ext-gd": "*"），哪怕你本地 PHP 确实启用了该扩展，只要 Composer 检测逻辑没走通（例如 CLI 和 Web 使用不同 php.ini、或扩展被注释但未真正禁用），就会报错中断安装。
直接跳过校验最常用的方式就是 --ignore-platform-req：
composer install --ignore-platform-req=ext-gd
注意：--ignore-platform-req 后必须跟具体扩展名（如 ext-gd），不能只写 gd；多个扩展需重复使用该参数：
composer install --ignore-platform-req=ext-gd --ignore-platform-req=ext-mbstring
- 只忽略单个扩展时，参数值不带空格、不加引号
- 如果要忽略所有平台要求（危险！），可用
--ignore-platform-reqs（复数形式，无等号） - 该参数仅影响本次命令，不会修改
composer.json或锁文件
为什么 --ignore-platform-req=ext-xxx 有时无效？
常见原因是参数拼写错误或作用范围不对。Composer 对扩展名大小写敏感，且必须严格匹配 php -m 输出的模块名（不含版本号）。
验证方式：
php -m | grep -i gd
若输出是 gd，则应写 ext-gd；若输出是 gd2（极少见），就不能写 ext-gd。
-
--ignore-platform-req只跳过require中的平台约束，不影响require-dev的平台检查（除非显式加上--dev） - 如果错误来自
platform-config（即config.platform配置项），--ignore-platform-req依然生效，但要注意它只忽略“扩展”，不忽略php版本本身（如php: ^8.1） - 某些 Docker 或 CI 环境中，PHP CLI 和 FPM 的扩展列表不一致，
composer install用的是 CLI，所以必须确保php -m能看到对应扩展
替代方案：用 config.platform 精确模拟目标环境
比起临时忽略，更稳妥的做法是在 composer.json 里声明你实际部署环境的平台能力：
"config": {
"platform": {
"php": "8.1.28",
"ext-gd": "8.1.28",
"ext-mbstring": "8.1.28"
}
}
这样 Composer 就不会去查真实环境，而是按你写的“假装”这些扩展存在。
- 适用于多环境（如本地开发用高版本 PHP，生产用低版本）
- 避免在 CI 脚本里堆砌一堆
--ignore-platform-req - 注意：这里填的版本号只是占位符，Composer 不校验其真实性，填
*也不合法，必须是类似"8.1.0"的字符串 - 该配置对
require-dev同样生效，除非你额外加--no-dev
CI/CD 中自动排除平台依赖的实用技巧
很多 CI 流水线（如 GitHub Actions）默认 PHP 环境缺少图形类扩展，每次手动加 --ignore-platform-req 易出错。推荐在 composer.json 的 scripts 里封装：
"scripts": {
"ci-install": "composer install --no-interaction --no-progress --ignore-platform-req=ext-gd --ignore-platform-req=ext-imagick"
}
然后 CI 中直接运行 composer run ci-install。
- 不要把
--ignore-platform-reqs当默认选项，它会掩盖真实兼容性问题 - 如果项目真依赖某个扩展的特定行为（比如 GD 和 Imagick 处理透明 PNG 方式不同），忽略后测试可能通过但线上出 bug
- GitLab CI 中若用
composer install报错，先确认是否用了composer/composer:2镜像 —— 它默认禁用所有扩展，必须显式安装或忽略
真正难处理的不是怎么跳过检查，而是搞清「这个扩展到底有没有被加载」——php -i | grep -A5 -B5 gd 比任何参数都管用。
