快速绕过 platform requirements 错误应使用 --ignore-platform-reqs 参数；若需精准跳过某扩展（如 ext-gd）则用 --ignore-platform-req=ext-gd；项目级永久关闭须在 composer.json 的 config 中设 "platform-check": false。
composer install 报 platform requirements 错误，怎么快速绕过？
这是最常见也最容易误解的场景：你执行 composer install，却卡在类似 Required platform extensions missing: mbstring, zip 或 Your PHP version (7.4.33) does not satisfy that requirement. 的报错上。这不是“依赖版本冲突”，而是 Composer 在校验你本地环境是否满足项目声明的平台要求（PHP 版本、扩展、lib 库等）。
- 这个检查默认开启（Composer 2.2+），发生在依赖解析之后、脚本执行之前，和
--no-scripts完全无关 -
--ignore-platform-reqs是唯一能跳过它的通用解法 - 它不改变 lock 文件内容，也不影响依赖选择逻辑，只让安装流程继续往下走
实操建议：
- 临时调试或 CI 构建中确认环境实际可用 → 直接加
composer install --ignore-platform-reqs - 只想跳过 ext-gd 但保留 PHP 版本检查 → 用
composer install --ignore-platform-req=ext-gd - CI 中需同时跳过多个项 → 可重复使用参数：
composer install --ignore-platform-req=php --ignore-platform-req=ext-igbinary
create-project 也卡住？命令参数不能省
composer create-project 不仅要下载模板，还要立刻 install 其依赖，所以它同样会触发 platform-check —— 而且更早、更严格。很多人加了 --no-interaction 或 --quiet 仍失败，就是因为这些参数根本不影响平台校验。
实操建议：
- 必须显式传参：
composer create-project laravel/laravel myapp --ignore-platform-reqs - 如果项目
composer.json里写了"config": {"platform": {"php": "8.3.0"}}，而你本地是 PHP 8.2，不加该参数会直接退出，根本不会开始下载 - 别指望
--no-dev或--prefer-dist能绕过这个环节 —— 它们作用于后续步骤
想永久关闭检查？别动全局配置，改项目级 config
有人想一劳永逸，跑去执行 composer global config platform-check false，这会污染所有项目，极不推荐。真正安全的做法是在当前项目 composer.json 中控制。
实操建议：
- 在
composer.json的config段加入："platform-check": false - 这样只对本项目生效，且优先级高于全局设置
- 注意：
platform-check: false只跳过“你有没有”的检查，不影响config.platform的模拟行为 —— 如果你同时写了"platform": {"php": "8.1"}，Composer 依然按 PHP 8.1 解析依赖 - 团队协作时务必 git commit 并说明原因，否则别人拉代码后可能忽略真实环境缺口
为什么加了 --ignore-platform-reqs 还报错？常见隐藏坑
不是所有“卡住”都源于 platform-check。如果你加了 --ignore-platform-reqs 仍然失败，大概率是其他环节出了问题。
常见原因：
-
ext-igbinary在旧版 PHP 上尝试加载失败并 hang 住（非报错，是卡死） - PHP 配置中
disable_functions禁用了shell_exec或exec，导致 Composer 内部调用失败后无限重试 - 第三方插件注入了自定义 platform-check 逻辑（少见，但存在）
- 真正的问题是 lock 文件与
composer.json不一致，而你误以为是 platform-check —— 可用composer install --dry-run验证
真正绕不过的时候，只能清掉引发问题的 config.platform 声明项，或者换一个更干净的 PHP 环境。把 --ignore-platform-reqs 当万能钥匙，最后往往在 runtime 才暴露问题，那时定位更难。
