Composer platform check 怎样发现 PHP 版本不兼容

Composer 发现 PHP 版本不兼容，关键不是只看本机安装的 Composer 版本，而是把项目依赖声明的 PHP 约束与实际执行 Composer 的 PHP 运行时进行比较。最直接的判断命令是 composer check-platform-reqs：它检查已安装依赖需要的 PHP 和扩展版本，并且不使用 config.platform 伪装出的平台值。

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

如果安装阶段看起来正常、部署后却报 PHP 版本错误，按“触发信号 → 真实检查 → 区分假设 → 修复或回滚 → 发布门禁”的顺序排查，通常可以很快定位是 PHP 本身、扩展还是锁文件范围的问题。

一、先确认问题发生在哪一层

Composer 的平台依赖是虚拟包，常见的 php 表示运行 Composer 的 PHP 版本，ext-* 表示 PHP 扩展，lib-* 表示系统库。项目在 composer.json 中声明这些约束后，Composer 会参与依赖解析；依赖安装完成后，生成的运行时平台检查还可能在应用启动时再次阻断不满足的环境。

因此要先区分两种信号：

• 安装或更新阶段失败：依赖求解器认为当前平台无法满足约束，常见于当前 PHP 太旧。
• 部署或启动阶段失败：锁定的依赖已经落地，但执行应用的 PHP 或扩展与依赖要求不一致。

这个区分决定了后面的检查对象：前者先看 Composer 使用的 PHP，后者要看部署进程实际使用的 PHP，不能只看开发机的版本。

二、用 check-platform-reqs 检查真实 PHP 版本

进入包含 composer.lock 和 vendor 的项目目录，先跑一次完整检查。下面的命令把关键判断分成三步，输出只作为示例格式，不代表某台机器的真实结果。

# 先确认当前 shell 调用的 PHP 版本
php -v

# 检查已安装依赖要求的真实 PHP 与扩展
composer check-platform-reqs

# 查看 Composer 当前识别到的平台包，便于核对 php 与 ext-* 条目
composer show --platform

官方命令文档说明，check-platform-reqs 会检查 PHP 和扩展的真实版本；它与安装或更新阶段不同，会忽略 config.platform，因此适合放在生产构建或部署前确认实际运行环境。

如果输出中出现 php 不满足，重点看两端的版本号：左侧是依赖要求，右侧是当前命令实际使用的 PHP。若出现 ext-mbstring、ext-curl 等条目，则问题是扩展缺失或版本不满足，不要把它误判成 PHP 主版本问题。

三、区分 config.platform 与真实环境

很多“本地能装、线上不能跑”的问题来自 config.platform。它可以让依赖解析阶段按照目标 PHP 版本进行假设，例如项目把解析平台固定成 PHP 8.1；这只改变 Composer 选版本时的计算前提，不会把服务器正在运行的 PHP 变成 8.1。

{
  "config": {"platform": {"php": "8.1.0"}},
  "require": {"php": ">=8.1", "ext-mbstring": "*"}
}

上面的 JSON 必须保持严格格式，所以不在代码块里添加注释。config.platform.php 是依赖解析假设，require.php 是项目或包声明的约束；服务器是否真的满足，仍然要用目标 PHP 进程执行平台检查。

若项目以锁文件作为发布依据，可以缩小检查范围：

# 只按 composer.lock 中的要求检查，避免把当前 vendor 状态混入判断
composer check-platform-reqs --lock

# 生产不安装开发依赖时，排除 require-dev 的平台要求
composer check-platform-reqs --no-dev

# 需要让 CI 读取结果时使用 JSON 输出
composer check-platform-reqs --no-dev --format=json

--lock 适合锁文件就是发布输入的流水线；--no-dev 适合生产构建。两者不是“忽略错误”的开关，而是明确检查集合。若要分析完整开发环境，不要误加 --no-dev。

四、按根因修复，保留可回滚路径

确定是 PHP 版本不兼容后，按部署环境能控制的范围选择方案。优先顺序通常是升级运行时、调整依赖约束、补齐扩展；只有确认项目代码与依赖都支持时，才进行约束迁移。

# 修复运行时后，使用锁文件重装生产依赖
composer install --no-dev --prefer-dist

# 只在明确要迁移项目约束时更新直接依赖，并保留变更记录
composer update --with-all-dependencies

# 修复后再次检查真实平台，失败时让脚本返回非零退出码
composer check-platform-reqs --no-dev

composer install 适合按现有锁文件重建环境；composer update 会重新求解依赖，可能扩大变更面，应在变更评审和回归测试后使用。不要把 --ignore-platform-reqs 当作修复方案：它只是跳过平台要求，可能把不兼容推迟到应用运行时。

如果修复后的发布结果不符合预期，回滚应同时恢复代码与对应的 composer.lock，再重新安装同一组依赖。不要只回滚 PHP 而保留新锁文件，也不要只删除 vendor 目录来“碰运气”。

五、把检查放进部署门禁

平台检查最好由部署脚本使用与应用相同的 PHP 可执行文件运行。只要检查返回非零状态，就停止后续发布，避免应用已经上线后才暴露 PHP 版本不兼容。

#!/usr/bin/env bash
set -euo pipefail

# 使用部署环境的 PHP 与 Composer 检查生产依赖要求
composer install --no-dev --prefer-dist --no-interaction
composer check-platform-reqs --no-dev --format=json

# 检查通过后才继续生成或切换发布目录
echo "平台依赖检查通过，允许继续发布"

如果流水线需要进一步区分失败类型，可以保存 JSON 输出并按 php、ext-* 归类告警。告警信息至少应包含运行环境、PHP 版本、缺失扩展、锁文件版本和对应构建号，方便回滚后复盘。

相关问题

为什么 Composer 能安装，应用启动时却提示 PHP 版本不满足？

可能是安装和启动使用了不同的 PHP 可执行文件，也可能是安装时设置了 config.platform。在部署进程使用的 PHP 下重新运行 composer check-platform-reqs，再核对 composer.lock。

--lock 和普通检查有什么区别？

--lock 只按锁文件中的平台要求检查；普通检查会结合已安装依赖。发布输入明确是锁文件时，--lock 更容易保持门禁范围稳定。

可以用 --ignore-platform-reqs 临时上线吗？

不建议把它作为上线策略。它会跳过平台要求，不能证明应用真的兼容；应先修复 PHP 版本或扩展，再让平台检查通过。