Composer怎么检测环境要求 check-platform-reqs命令详解【工具】

composer check-platform-reqs 是 Composer 3.0+ 的独立平台依赖校验命令，严格检测 php 版本、扩展及 INI 设置是否满足 composer.json 声明，不安装包、不读锁文件，专用于环境一致性验证。

composer check-platform-reqs 是 Composer 3.0+ 引入的专用命令，用于**独立检测当前 PHP 环境是否满足项目 composer.json 中声明的平台依赖（如 PHP 版本、扩展、INI 设置）**。它不安装包、不读取锁文件，只做静态环境校验——这是它和 composer install 或 composer update 的本质区别。

为什么 check-platform-reqs 比直接看报错更可靠

很多团队在 CI 或部署时遇到 PHP extension "gd" is required 这类错误，但本地能跑通。问题常出在：环境差异被忽略、扩展虽已加载但 INI 配置禁用（如 opcache.enable=0）、或 PHP 版本小版本不兼容（如要求 ^8.1.10，而系统是 8.1.9）。check-platform-reqs 会严格比对 platform 和 platform-check 配置项，并报告所有不匹配项，包括：

• PHP 主版本、次版本、修订号（如 php: ">=8.2.0 ）
• 扩展是否存在且启用（ext-gd, ext-mbstring）
• INI 值是否符合要求（memory_limit >= 256M, opcache.enable = on）

check-platform-reqs 默认行为与常见参数

运行 composer check-platform-reqs 时，默认只检查 composer.json 中 require 下的平台包（php, ext-*, lib-* ），不检查 require-dev。关键参数有：

• --no-dev：显式跳过 require-dev（默认已如此，加了也无害）
• --ignore=ext-xdebug：临时忽略某个扩展（适合开发机装了 Xdebug 但生产不需）
• --strict：把警告（如 INI 值偏低）升级为错误，让 CI 失败（推荐在 CI 脚本中加上）
• --format=json：输出结构化 JSON，便于脚本解析（例如 CI 中提取 failed 字段）

示例：composer check-platform-reqs --strict --format=json | jq '.failed' 可直接判断是否通过。

容易被忽略的配置影响：platform 与 platform-check

如果项目 composer.json 含有 "config": {"platform": {...}}，check-platform-reqs 会**优先使用该配置模拟平台环境**，而非真实环境。这会导致误报（比如你本地 PHP 是 8.2，但 platform 设为 "php": "8.1.0"，命令就假装自己在 8.1 上跑）。真正想测真实环境，必须删掉或注释掉 platform 配置。另外，Composer 2.5+ 支持 "platform-check": true/false 控制是否启用平台检查——设为 false 会让 check-platform-reqs 直接跳过所有检查，慎用。

最常踩的坑不是命令不会用，而是没意识到 platform 配置会覆盖真实环境；还有人把 check-platform-reqs 当成万能健康检查，忘了它不验证扩展功能是否正常（比如 GD 扩展存在但不支持 WebP），那些得靠单元测试或运行时断言。