PHP Composer 平台检查 怎样处理

Composer 报“平台要求不满足”时，先不要急着把 --ignore-platform-reqs 加上。这个错误通常来自三种实体：项目要求的 PHP 版本、某个 ext-* 扩展，或 Composer 自身的运行时 API。正确处理方式是先列出本机真实平台，再区分依赖解析时的目标平台，最后用真实服务器环境复查已经安装的依赖。

官方地址：https://getcomposer.org/

先区分解析平台与真实运行平台

Composer 会把 PHP、扩展和系统库表示为平台包，例如 php、ext-mbstring、lib-curl。先查看当前环境能提供什么：

# 查看当前 PHP、扩展和库对应的平台包
composer show --platform

# 只筛选 PHP 与扩展，便于对照报错中的名称
composer show --platform | grep -E '^(php|ext-)'

如果输出里没有报错所指的 ext-intl，问题是扩展缺失；如果 PHP 版本低于项目的 require.php，就应调整运行时或重新评估兼容范围。不要把“解析器找到了一个版本”误认为“线上机器可以运行”。

config.platform 能模拟目标版本，但不能补齐能力

团队常在开发机上写入 config.platform，让依赖解析按生产 PHP 版本选择包。它适合提前暴露“生产版本过低”的约束冲突，但它不是安装 PHP 或扩展的替代品。

{
  "require": {
    "php": ">=8.2",
    "ext-mbstring": "*"
  },
  "config": {
    "platform": {
      "php": "8.2.0",
      "ext-mbstring": "8.2.0"
    }
  }
}

上面的 JSON 仍然是严格数据，不能写注释。platform 的作用是改变解析器看到的版本；即使本机实际是更高版本，Composer 也会按 8.2.0 约束选择依赖。相反，若服务器真实缺少 ext-mbstring，这段配置不会安装扩展，应用启动时仍可能失败。

排查时把问题拆成两张表：一张记录 composer.json 和 lock 文件表达的目标，一张记录服务器 php -v、扩展清单和 Composer 版本。两张表的差异，往往比继续重试 install 更快暴露根因。

安装通过后仍要做真实环境复查

部署机器上建议直接检查 lock 文件对应的已安装依赖：

# 按 composer.lock 检查真实 PHP 与扩展，不采用 config.platform 的假设
composer check-platform-reqs --lock

# 只检查生产依赖，避免测试依赖影响部署结论
composer check-platform-reqs --lock --no-dev

这个命令的关键点是“检查真实平台”：它不会把 config.platform 当成服务器能力，而是核对当前 PHP 与扩展。若项目还启用了运行时平台检查，Composer 生成的 platform_check.php 也会在加载 autoloader 时提供一层保护；它能尽早报错，但不能代替部署前的完整复查。

忽略参数只解决局部构建阻塞

--ignore-platform-req=ext-foo 只忽略一个明确平台要求；--ignore-platform-reqs 会忽略 PHP、扩展和库等全部平台要求，风险明显更大。比如文档构建机不运行应用，可以临时忽略一个不参与构建的扩展，但生成的 lock 文件和部署产物仍应在真实环境复查。

# 仅在明确知道构建机不需要该扩展时临时放宽一项
composer install --ignore-platform-req=ext-gd

# 生产部署不要用全量忽略来掩盖缺失的 PHP 或扩展
# composer install --ignore-platform-reqs

如果是上限约束与本机版本冲突，可以先确认项目是否真的支持更高版本，再考虑带 + 的单项忽略方式；不要用它跳过下限。最终判断标准不是 Composer 命令退出成功，而是应用所需的真实 PHP、扩展和库都能在目标环境被复查。

常见问题

为什么写了 config.platform 仍然在服务器报错？

因为它只影响依赖解析，服务器仍按真实 PHP 和扩展加载应用。部署前运行 composer check-platform-reqs --lock 才能发现真实缺项。

check-platform-reqs 和 install 的平台检查有什么区别？

install 主要保证安装过程能满足解析条件；check-platform-reqs 专门核对已安装依赖与当前真实平台，并忽略 config.platform 的模拟值。

可以一直使用 --ignore-platform-reqs 吗？

不建议。它可能让不具备运行条件的依赖进入产物，应该改为补齐服务器能力或修正经验证的约束，并把忽略范围缩小到单项构建场景。