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。
