composer不支持按操作系统条件安装依赖，因ext-inotify等os专属扩展写入require会导致跨平台安装失败；应通过config.platform模拟环境并配合运行时extension_loaded()判断实现兼容。
Composer 本身不支持按操作系统声明 require 依赖，所谓“OS 限定安装”必须靠 platform 配置 + 运行时判断组合实现，硬写 ext-xxx 到 require 会导致跨平台 CI 失败或运行时 fatal error。
为什么 composer.json 里不能直接写 "ext-inotify": "*" 作为 OS 条件？
因为 ext-inotify 是 Linux 专属扩展，Windows/macOS 上天然不存在。一旦你把它放进 require，Composer 在 Windows 上执行 composer install 就会报错：Your requirements could not be resolved to an installable set of packages. ext-inotify is missing from your system.
这不是 bug，是 platform-check 的正常拦截——它检测到当前环境不满足 require 声明的约束，就拒绝解析依赖树。
常见误操作包括：
- 把仅用于 CLI 工具的扩展（如
ext-pcntl）放在require而非require-dev - 在
composer.json根级误写"platform": {...}（正确路径是config.platform） - 用
"ext-gd": "^8.2"这类带版本运算符的写法（config.platform只接受具体字符串，如"8.2.12"）
如何让 Linux 才装 ext-inotify，而 Windows 自动跳过？
唯一可靠方式是：**不把它放进 require，改用运行时检测 + 条件加载**。
例如，在代码中这样写：
if (extension_loaded('inotify') && PHP_OS_FAMILY === 'Linux') {
$watcher = new InotifyWatcher();
}
同时确保：
-
ext-inotify不出现在require或require-dev中 - 如果该功能是可选的（比如只用于开发环境的文件监听），可将其封装成独立服务，并通过容器或配置开关控制启用
- 若必须由 Composer 安装对应包（如
inotifywait的 PHP 封装），应确认该包是否在composer.json中正确声明了conflict或provide，避免被错误选中
CI/CD 中如何统一锁定 Linux 环境的依赖？
关键不是“让 Composer 按 OS 安装”，而是“告诉 Composer：我最终部署到 Linux，所以请按 Linux 的能力来选包”。这靠 config.platform 实现。
在 composer.json 的 config 段写：
"config": {
"platform": {
"php": "8.2.12",
"ext-inotify": "0.1.0"
}
}
注意：
- 这个配置不会让你本地 Windows 装上
ext-inotify，但它会让composer update在生成composer.lock时，允许那些声明了"require": {"ext-inotify": "*"}的包进入依赖树 -
ext-inotify的版本号填什么不重要（填"0.1.0"或"dev-main"都行），只要字段存在，platform-check 就认为“已满足” - 该配置对
require-dev同样生效，所以测试工具链也能被正确锁定
哪些情况真该用 --ignore-platform-req？
只在两种场景下临时使用：
- 调试阶段快速验证某包是否真的依赖某个扩展（比如怀疑
ext-sodium其实没被调用） - CI 脚本中明确知道目标环境已预装对应扩展，但 PHP CLI 配置未加载（如 Dockerfile 中漏了
docker-php-ext-enable sodium）
绝对不要：
- 提交含
--ignore-platform-req的 CI 配置到主干分支 - 在
composer.json的scripts里硬编码该参数（"post-install-cmd": "composer install --ignore-platform-req=ext-posix"） - 忽略后不补运行时检查——
--ignore-platform-req=ext-posix不等于posix_getpid()就能用
最易被忽略的一点：platform-check 报错时，第一反应不该是绕过，而是查清那个扩展是否真被业务代码执行路径覆盖。很多所谓“OS 依赖”，其实只是某个 dev-only 工具的副作用，挪到 require-dev 就解决了。
