最稳妥做法是配置 config.platform 声明目标部署环境的 PHP 和扩展版本，使 Composer 在依赖解析阶段自动剔除不兼容包；需确保上游包规范声明 ext-xxx 依赖，且 platform 配置位于 composer.json 的 config 下而非根级。
composer install 时如何只装当前操作系统需要的包
Composer 默认会安装 require 和 require-dev 下所有包，不管当前系统是否用得上。比如 Windows 下装了 ext-pcntl 相关扩展包，或 Linux 下装了 win32service 扩展封装器，不仅浪费空间，还可能因扩展缺失导致 autoload 失败或运行时报错。
真正可控的方式是：把 OS/平台相关依赖移到 require-platform + platform-check 配合 config.platform 模拟，但更直接有效的做法是——**用 platform 配置 + 条件性 require（即“平台限定依赖”）**，靠 Composer 自身的 platform 约束机制过滤。
-
composer.json中不直接写平台敏感包到require，而是用provide声明能力，并配合replace或conflict控制安装逻辑 - 实际项目中更常用的是：把平台专属包放进
require-dev，再通过config.platform强制“假装”当前环境不满足条件，从而跳过安装（需搭配--ignore-platform-req的反向操作） - 但最稳妥、官方支持的做法是：使用
composer require时加--platform参数（仅限 Composer 2.2+），或在composer.json中设置config.platform锁定目标部署环境的 PHP/扩展版本，让 Composer 在解析依赖图时主动剔除不兼容包
platform 配置怎么写才生效
config.platform 不是“声明当前环境”，而是“告诉 Composer：我最终要部署到这个平台，所以请按这个平台的能力来选包”。它影响依赖解析阶段，不是运行时检测。
常见错误是写成："platform": {"php": "8.1.0"} —— 这个字段名错了，正确路径是 config.platform，且必须在 composer.json 根对象的 config 下：
{
"config": {
"platform": {
"php": "8.1.10",
"ext-sodium": "1.0.0",
"ext-redis": "5.3.7"
}
}
}
这样配置后，Composer 安装时会认为：目标环境只有这些扩展可用，因此不会选依赖 ext-pcntl 或 ext-mbstring（如果没在 platform 里声明）的包 —— 前提是那些包的 require 确实写了对应扩展约束。
- 仅当包的
composer.json显式写了"ext-pcntl": "*"，且你没在config.platform里提供该扩展，Composer 才会跳过它 -
config.platform对php版本的模拟最可靠；对扩展的模拟，依赖于上游包是否规范声明了ext-xxx - Windows 下想排除
ext-inotify类 Linux-only 包？只要不把它写进config.platform，且对应包 require 了ext-inotify，它就不会被装
require-dev 中的平台包怎么避免误装
很多工具类包（如 phpunit/phpunit、symfony/console）本身不平台敏感，但某些插件或驱动（如 phpstan/phpstan 的 phpstan-phpunit 扩展）可能依赖 ext-posix。开发时在 macOS 装了没问题，CI 流水线跑在 Alpine Linux 就可能失败。
解决思路不是删掉 require-dev，而是用 platform-check 插件或 CI 阶段手动干预：
- 在 CI 的
composer install命令后加--no-scripts --no-plugins，防止自动加载触发平台检测失败 - 对明确只用于某系统的 dev 包（如 Windows 的
laravel/sail替代方案laravel/valet），改用require并配合conflict排除其他平台："conflict": { "php": "!=8.1.*" }不够精准，应写："conflict": { "ext-pcntl": "*" }（表示“如果存在 pcntl 扩展，就冲突”，从而阻止在 Linux/macOS 上安装） - 更干净的做法：把这些包移出主
composer.json，用composer create-project模板或composer config repositories动态注入，按系统选择不同 repo
为什么 vendor/bin/xxx 在 Windows 下找不到命令
这不是 Composer 包安装问题，而是 vendor/bin 下生成的可执行文件格式导致的。Linux/macOS 是 shell 脚本（#!/usr/bin/env php），Windows 默认不识别。Composer 2.2+ 会在 Windows 下额外生成 .bat 文件，但前提是：原包的 bin 配置正确，且没有被 config.platform 错误干扰。
检查点：
- 确认包的
composer.json有"bin": ["xxx"]字段，且xxx文件第一行是#!/usr/bin/env php - 运行
composer install -v，看日志里是否出现Generating autoload files后的Creating script xxx for package xxx - 如果用了
config.platform且锁死了php版本，但本地 PHP 是 8.2，而 platform 设为 8.1，Composer 可能跳过 bin 生成（因认为环境不匹配） - 临时解决：删掉
vendor和composer.lock，清空config.platform后重装，确认vendor/bin/xxx.bat是否生成
平台包的真正难点不在安装，而在“谁在什么时候、以什么方式调用它”——config.platform 是开关，不是胶水；它不帮你做适配，只帮你筛掉明显不兼容的选项。剩下那部分，得靠包作者写对 ext-xxx、靠你自己管住 require-dev 的边界。
