优化Composer库在CI构建环境中的PHP扩展自动检出逻辑-composer-PHP中文网

答案：ci构建时ext-xxx报错是composer校验php cli环境缺失扩展，需用composer check-platform-reqs --with-dependencies定位真实缺口，通过config.platform虚拟声明或真实安装扩展解决。

优化composer库在ci构建环境中的php扩展自动检出逻辑

CI 构建时 ext-xxx 报错不是网络问题，是 Composer 在校验环境

Composer 从不安装 PHP 扩展，它只在 composer install 或 composer update 前调用 extension_loaded() 检查扩展是否启用。报错如 Your platform does not meet the minimum requirements: ext-pcntl is missing，说明某依赖（比如 amphp/amp 或 laravel/octane）在 composer.json 的 require 中声明了硬依赖，而当前 CI 环境的 PHP CLI 未加载该模块。

常见陷阱：

你运行 php -m | grep pcntl 看到结果，但 composer install 用的是另一个 PHP 二进制（比如 /usr/bin/php vs /opt/php/bin/php），用 which php 和 composer config --global bin-dir 对齐路径
Docker 镜像用了 php:8.2-cli，但它默认不装 ext-gd、ext-xml 等——这些不是“可选”，而是很多包（如 symfony/console）的隐式依赖
GitHub Actions 默认 Ubuntu runner 没启用 mbstring 或 ctype，导致 phpunit 启动失败，不是测试代码问题

别用 --ignore-platform-reqs，改用 config.platform 做项目级模拟

--ignore-platform-reqs 是全局跳过，会污染 composer.lock 的兼容性保证；CI 构建阶段真正需要的是“让 Composer 认为扩展存在”，而非掩盖缺失。最稳妥做法是在项目 composer.json 的 config.platform 下虚拟声明：

{
  "config": {
    "platform": {
      "ext-pcntl": "0",
      "ext-posix": "0",
      "ext-gd": "0",
      "ext-xml": "0"
    }
  }
}

注意：

版本号填 "0" 或 "1.0.0" 即可，Composer 不校验真实性，只用它通过“已安装”逻辑
该配置会被写入 composer.lock，团队成员拉代码后无需额外操作
若某天真要在生产启用 pcntl，删掉这行就能立刻暴露问题，不埋雷
Windows 开发机或最小化 CI 镜像（如 php:8.2-cli-slim）适用此法；Linux 生产环境仍需真实安装扩展

用 composer check-platform-reqs 提前暴露真实缺口

composer diagnose 只查 Composer 自身依赖（json、mbstring、curl 等），而 composer check-platform-reqs（Composer 2.2+）才真正读取所有依赖项的 require 字段，包括传递依赖。CI 流程中应在 composer install 前加这一步：

Docker Compose Linter

检查 docker-compose.yml 文件的安全问题、最佳实践和端口冲突

下载

composer check-platform-reqs --with-dependencies

输出里出现 ext-zip * missing 就代表某个下游包（比如 spatie/laravel-backup）要求它，哪怕你没直接 require。

关键差异：

--with-dependencies 必须加，否则只检查顶层 composer.json，漏掉深层依赖
它不触发下载或 autoload 生成，纯静态检查，快且安全
和 composer install --dry-run 不同：后者会初始化 autoloader，可能因 PSR-4 映射错误提前崩溃

CI 环境 PHP 二进制和扩展路径必须显式对齐

CI 脚本里不能假设 php 命令指向你期望的版本和配置。Ubuntu runner、GitLab shared runner、自建 k8s node 的 PHP 安装方式千差万别。

实操建议：

用完整路径调用 PHP：/usr/bin/php -m | grep gd，再对比 composer install 实际用的 PHP（可通过 php -v 和 composer --version 输出中的 PHP 版本交叉验证）
确认 CLI 模式生效的 php.ini：/usr/bin/php --ini，确保 extension=gd.so 这类行未被注释，且路径正确（.so vs .dll）
GitHub Actions 推荐用 shivammathur/setup-php，它支持 extensions: gd, mbstring, xml, zip 参数，比 actions/setup-php 更可靠
GitLab CI 中避免用 apt-get install php-gd，优先用镜像自带扩展（如 php:8.2-cli + docker-php-ext-install gd）