platform-check-file 是 composer 2.5+ 的静态平台快照配置项，需与 "platform-check": false 同时设置才生效，仅用于 ci/cd 等环境不可控场景，不解决真实扩展缺失问题。
platform-check-file 是什么，为什么它不生效
platform-check-file 是 Composer 2.5+ 引入的配置项，用于指定一个 JSON 文件，让 composer install 或 composer update 在执行平台检查（比如 PHP 版本、扩展是否可用）时，**跳过默认的 php -v 和 php -m 实时检测**，改用你提供的静态快照。但它只在 composer.json 的 config 段里声明才起作用，且必须配合 "platform-check": "false" 才真正绕过运行时检查——很多人只配了文件路径却没关掉检查开关，结果还是报错。
-
platform-check-file本身不触发任何行为，它只是“备用数据源” - 必须同时设置
"platform-check": false，否则 Composer 仍会先跑真实环境检查，失败就直接退出，根本不会读你的文件 - 该文件内容必须是合法 JSON，格式要严格匹配 Composer 内部预期：
{"php": "8.1.22", "ext-curl": true, "ext-json": true}，键名大小写敏感，ext-前缀不能少 - 路径支持相对路径（相对于
composer.json所在目录），但不能用~或环境变量，比如./ci/platform.json可以，$HOME/platform.json不行
怎么写 platform.json 才不会被 Composer 拒绝
这个文件不是随便写的配置，它是“模拟运行环境”的快照，Composer 会用它替代真实 php -v 和 php -m 输出。写错最常见的是版本号格式和扩展布尔值。
- PHP 版本字段必须叫
php，值为字符串（如"8.2.10"），不能是"PHP 8.2.10"或数字8.2 - 扩展名必须带
ext-前缀，比如"ext-opcache"，写成"opcache"或"Opcache"都会被忽略 - 扩展值只能是
true或false，不能是"1"、"on"、null或缺失 - 如果项目依赖
ext-gd，但你的platform.json里没写它，或者写了"ext-gd": false，Composer 仍会报错：“Package requires ext-gd, not available”
什么时候该用 platform-check-file，什么时候不该碰它
它只适合 CI/CD 构建或容器化部署中「环境不可控但目标明确」的场景。比如 GitHub Actions 里用 shivammathur/setup-php 安装 PHP，但 Composer 启动时检测到系统默认 PHP（可能是 7.4），导致安装失败——这时用 platform-check-file 告诉 Composer：“别信系统，信我给的”。但它不适合本地开发调试，也不解决扩展真的缺失的问题。
- 适用：CI 流水线中 PHP 版本/扩展由工具链管理，但宿主机环境混乱；Docker 构建阶段需要复用缓存，避免每次重装 vendor
- 不适用：本地
composer install报错想绕过检查——这说明你环境真缺东西，绕过去只会让运行时报错更晚、更难查 - 注意：它不影响
require中的php版本约束（如"php": "^8.1"），那些依然会校验；它只影响扩展和 PHP 小版本兼容性判断 - 性能上无开销，因为只是读一个 JSON 文件；但若文件路径错误或权限不足，Composer 会静默忽略它，继续走默认检查——所以建议加个
ls -l确认路径存在
实际配置示例和验证方法
假设你希望 Composer 相信当前环境有 PHP 8.2.12 和 ext-curl、ext-mbstring，但不检查 ext-redis（因为构建时不需它）：
{
"config": {
"platform-check": false,
"platform-check-file": "./platform.json"
}
}
对应 platform.json 内容：
{
"php": "8.2.12",
"ext-curl": true,
"ext-mbstring": true
}
验证是否生效：运行 composer install -vvv，看日志里有没有 Reading platform overrides from ./platform.json；如果没出现，检查路径是否拼错、文件是否可读、platform-check 是否设为 false。另外，故意把 platform.json 里的 "ext-curl" 改成 false，再运行 composer install，应该立刻报错——说明它确实在用这个文件做判断。
最常被忽略的一点：这个机制只对当前项目生效，不会影响全局 Composer 行为；而且一旦你在 composer.json 里删掉 platform-check-file，又没同步删掉 platform-check: false，Composer 就会因找不到文件而报错 “Platform check file not found”，而不是自动回退——得手动改回来。
