platform-check 是 Composer 2.2+ 默认启用的平台兼容性检查机制，安装前校验本地 PHP 环境（php 版本、扩展、库）是否满足 composer.json 中声明的 platform 或依赖 require 约束。

Composer 的 platform-check 是什么？

platform-check 是 Composer 2.2+ 引入的默认行为，它会在安装前检查当前 PHP 环境（包括 php、ext-*、lib-*）是否满足 composer.json 中声明的 platform 或依赖包的 require 约束。它本身不处理“仅限某操作系统”的依赖，但会因平台差异触发失败——比如某个包在 require 中写了 "ext-sodium": "*"，而 Windows 上未启用该扩展，就会报错。

如何让依赖只在特定操作系统安装？

Composer 原生不支持按 OS 条件安装依赖（例如 “只在 Linux 装 ext-redis”）。但可通过以下方式间接实现：

• 用 require + platform 配置伪造环境：在 composer.json 中设置 "platform": {"ext-sodium": "dev"}，可跳过扩展检查，但风险高，不推荐用于生产
• 用 require-dev 隔离非跨平台工具：如 phpunit/phpunit 可放 require-dev，再配合 CI 脚本控制安装范围
• 用脚本钩子动态处理：在 post-install-cmd 或 post-update-cmd 中调用 shell 判断 $OSTYPE 或 php_uname('s')，再执行 composer require --no-update 或删包
• 更稳妥的做法是：把 OS 特定逻辑下沉到代码层，用 extension_loaded() 或 function_exists() 运行时判断，而非强依赖安装时存在

platform-check 报错常见场景和绕过方式

典型错误信息类似：Your requirements could not be resolved to an installable set of packages. ... ext-gmp is missing from your system.。这往往不是因为系统真缺扩展，而是 Composer 检测到了不匹配。

• 在 Docker 或容器中，PHP CLI 和 FPM 使用不同配置，导致 composer install 时检测的是 CLI 的扩展列表，而运行时是 FPM 的——应统一使用 php -m 核对
• Windows 上某些扩展（如 ext-inotify）天然不可用，若依赖包未正确声明 conflict 或 provide，就会误报；此时应检查该包是否真的需要该扩展，或提交 issue
• 临时关闭检查：运行 composer install --ignore-platform-reqs（不安全），或更精细地忽略单个项：composer install --ignore-platform-req=ext-sodium
• 长期方案：在 composer.json 中显式声明目标部署平台，例如：

  {
      "config": {
          "platform": {
              "php": "8.2.10",
              "ext-zip": "8.2.10"
          }
      }
  }

  这样 Composer 就不会再去探测本地环境

真正需要 OS 限定时，应该怎么做？

Composer 不是条件安装引擎。如果你的项目必须在 Linux 上装 ext-ssh2、在 macOS 上装 ext-mcrypt（已废弃，仅作示例），说明架构设计已偏离 Composer 的语义边界。这时候应：

• 放弃在 composer.json 中硬编码这类依赖
• 将它们移至部署文档或 Ansible / Puppet 脚本中统一管理
• 用 composer create-project + 自定义 installer script 替代标准 install 流程
• 接受一个事实：Composer 的 platform-check 是守门人，不是调度器——它只保证“能装”，不负责“该不该装”

最容易被忽略的一点：很多所谓“OS 专属依赖”，其实是扩展编译产物的问题（比如 ext-rdkafka 在 Windows 上需额外 DLL），而不是 Composer 本身限制。解决路径永远优先从扩展构建入手，而非绕过 platform-check。

# php  # puppet  # ansible  # 就会  # 只在  # 报错  # 而非  # 的是  # 会在  # 这类  # 写了  # 自定义  # issue  # macos  # require  # linux  # redis  # js  # json  # docker  # composer  # windows  # 操作系统  # 编码  # 工具  # 架构  # 不支持