Composer install 因 PHP 扩展失败是因默认检查 platform 约束（如 ext-redis），缺失即报错；可用 --ignore-platform-reqs 全局跳过或 --ignore-platform-req 精准忽略，但不解决运行时错误。

为什么 composer install 会因 PHP 扩展失败？

Composer 默认检查 php 版本和已启用的扩展（如 ext-gd、ext-mbstring），确保运行时环境满足 composer.json 中 require 或 require-dev 的 platform 约束。如果本地没装 ext-redis，但 composer.json 声明了 "ext-redis": "*"，就会报错：Your requirements could not be resolved to an installable set of packages.

用 --ignore-platform-reqs 跳过全部平台检查

该参数强制 Composer 忽略所有 php、ext-*、lib-* 的平台约束，只按依赖逻辑安装包。适合开发环境快速拉取依赖，或 CI 中临时绕过扩展缺失问题。

  • 仅跳过检查，不解决运行时缺失扩展导致的 Fatal Error
  • 不会跳过 php 版本语法兼容性校验（如 PHP 8.2 安装只支持 PHP 7.x 的包仍会失败）
  • 与 --no-scripts 配合使用更安全，避免因扩展缺失导致 post-install-cmd 失败
composer install --ignore-platform-reqs

精准忽略某几个扩展：用 --ignore-platform-req

相比全局忽略，这个参数允许你只绕过特定项，保留其余检查。例如只忽略 ext-imagick 和 php 小版本差异：

  • 每个要忽略的项需单独加一次 --ignore-platform-req
  • 值必须完全匹配 composer.json 中声明的键名（如 ext-redis，不能写成 redis）
  • 支持通配符：--ignore-platform-req="ext-*" 会忽略所有扩展检查（但不推荐）
composer install --ignore-platform-req=ext-imagick --ignore-platform-req=php

永久忽略的配置方式（慎用）

在 composer.json 里加 config.platform 可伪造平台环境，让 Composer “以为”某些扩展已存在：

{
    "config": {
        "platform": {
            "php": "8.1.0",
            "ext-redis": "5.3.7",
            "ext-gd": "8.1.0"
        }
    }
}

这种写法本质

是欺骗依赖解析器，不改变真实环境。上线前务必确认对应扩展已在生产环境启用，否则运行时直接报 Class 'Redis' not found。

真正难处理的不是怎么跳过检查，而是跳过后没人验证这些扩展是否真能用 —— 尤其是 ext-sodium 这类默认启用但可能被编译时禁用的扩展。