composer如何配置platform-check-file_composer自定义平台检查文件【灵活】

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”，而不是自动回退——得手动改回来。