platform-check 是 Composer 2.2+ 默认启用的环境校验机制，用于 install/update 前检查 PHP 版本及扩展（如 ext-json）是否已加载；失败主因是 CLI 与 Web SAPI 环境不一致或 PHP 编译时禁用 json。

Composer 不会自动安装或启用 PHP 扩展，它只检查当前运行环境是否已加载所需扩展（如 ext-json），并在不满足时直接报错退出。

platform-check 是什么，为什么它会失败？

platform-check 是 Composer 2.2+ 默认启用的机制，用于在 install 或 update 前验证当前 PHP 环境是否满足 composer.json 中声明的 platform 要求（包括 PHP 版本和扩展）。它不查 php.ini 配置文件，只调用 extension_loaded() 检查扩展是否已加载。

• 常见失败现象：Your requirements could not be resolved to an installable set of packages. 后紧跟 ext-json is missing from your system
• 即使 php -m | grep json 显示存在，也可能因 CLI 和 Web SAPI 使用不同 php.ini 导致不一致
• 如果项目指定了 "ext-json": "*" 但当前 PHP 是以 --disable-json 编译的，platform-check 会立即中断

如何绕过或调整 platform-check 行为？

绕过不是推荐做法，但调试时可用；更稳妥的是显式声明或修正环境。以下操作均作用于当前命令执行，不影响全局配置：

accurLex专业合同审查

基于5000余部现行法律法规进行的高质量专业合同审查，一键输出审查意见书，并附有参考法条原文，满足专业溯源核查要求。由accurLex知法提供技术支持。 Use when users ask for 合同审查, 审查意见书, 合同风险分析, 条款审查,知法,accurLex or 站在甲方/乙方角度审查合同 through accurLex direct API. China law only, plaintext only, review mode limited to 审查意见书.

下载

• 临时跳过检查：composer install --ignore-platform-req=ext-json
• 跳过所有扩展检查：composer install --ignore-platform-reqs（⚠️ 危险，可能装入不兼容包）
• 强制指定平台版本（模拟环境）：composer install --platform=ext-json:7.4，这会让 Composer 认为 ext-json 已就绪，但实际运行时仍可能报 Call to undefined function json_encode()
• 在 composer.json 中显式声明你接受的平台约束（更透明）：

  {
      "config": {
          "platform": {
              "php": "8.1.0",
              "ext-json": "8.1.0"
          }
      }
  }

为什么 ext-json 会“突然”报错，而其他扩展不会？

ext-json 是少数几个被 Composer 内部硬编码为「必需」的扩展之一——即使你没在 composer.json 里写 "ext-json": "*"，某些包（如 symfony/console、laravel/framework）的 composer.lock 或依赖树中可能间接要求它，且 Composer 会主动校验。其他扩展（如 ext-curl）通常只在运行时报错，不参与 platform-check。

立即学习“PHP免费学习笔记（深入）”；

• PHP 8.3+ 开始，json 扩展已无法被完全禁用（编译时默认启用），但旧版 PHP 或自定义编译环境仍可能缺失
• Docker 用户常踩坑：CLI 容器里启用了 json，但 FPM 容器没同步配置，导致部署后 Web 请求失败
• 使用 phpbrew 或 asdf 切换 PHP 版本时，扩展未随版本重装，platform-check 会立刻暴露问题

真正的问题往往不在 Composer，而在 PHP 环境本身是否一致启用——检查 php -i | grep json 和 php -r "var_dump(extension_loaded('json'));" 比调参数更重要。