PHP Composer 平台依赖不满足时怎么定位真实运行时版本

Composer 报“平台依赖不满足”时，先不要急着加 --ignore-platform-reqs。最可靠的定位顺序是：先确认当前命令到底调用了哪个 PHP，再用 composer check-platform-reqs 检查已安装依赖需要的真实 PHP 和扩展，最后对照 composer.json 的 require、config.platform 与 composer.lock。这样能区分“依赖声明冲突”“扩展没装”和“CLI/FPM 不是同一个运行时”。

先分清 Composer 检查的三类平台信息

Composer 所说的平台包不只包含 PHP 本身，还包括 ext-json、ext-mbstring 这类扩展以及部分运行库。项目的 require 描述“依赖需要什么”，当前 PHP CLI 和已加载扩展描述“机器有什么”，而 config.platform 可以人为声明“求解时假定机器有什么”。三者不一致，就容易出现本地安装成功、部署启动失败。

尤其要注意命令行 PHP 和 PHP-FPM 的差异。你在 shell 里看到的 php -v 只代表 CLI；Web 请求可能由另一套 FPM 版本和另一份 php.ini 处理。Composer 报错时，先记录执行 Composer 的 PHP 路径与版本，再去比对实际承载请求的服务。

用 check-platform-reqs 确认真实运行时

在项目根目录执行下面的检查。它针对已安装依赖验证 PHP 和扩展，并不会被 config.platform 的模拟值替代。

# 先确认当前 shell 使用的 PHP 与已加载扩展
command -v php
php -v
php -m

# 检查 vendor 对真实 PHP/扩展平台的要求
composer check-platform-reqs

# 需要交给 CI 解析时输出 JSON；只检查锁定依赖可加 --lock
composer check-platform-reqs --format=json
composer check-platform-reqs --lock --no-dev

如果输出指出 ext-intl 或 ext-redis 缺失，先确认扩展是否装在“执行 Composer 的这套 PHP”里，而不是只看系统中是否存在某个 so/dll 文件。若是 PHP 版本不满足，则记录当前版本、依赖要求和部署镜像标签，避免直接把约束改宽。

沿着 composer.json 与 lock 文件定位来源

接下来回到项目文件。install 在存在 composer.lock 时会按锁定版本安装，因此只改了 composer.json 却没有重新生成 lock，往往不能得到预期结果。排查时可以按下面的关系看：

# 查看当前项目声明与 Composer 解析到的平台包
grep -n '"php"\|"ext-' composer.json
composer show --platform

# 查看配置是否人为模拟了 PHP 或扩展版本
composer config platform --list

# 只在确实要重新求解依赖时更新，再重新检查真实平台
composer update --lock
composer check-platform-reqs

composer show --platform 适合查看 Composer 当前可见的平台包；但要判断生产环境能不能运行，仍以部署机上的 check-platform-reqs 为准。若项目设置了 {"php":"8.2"} 之类的 config.platform，本地可能按模拟版本完成求解，生产机却只有 PHP 8.1，这就是“安装时没问题、启动时报错”的典型来源。

按错误类型修复，不要把检查整体关掉

扩展缺失通常应在 PHP 镜像或服务器安装并启用对应扩展；版本不满足则要在兼容的 PHP 运行时、依赖版本和项目约束之间做选择。若 CLI 与 FPM 不一致，分别查看两套 php.ini、扩展目录和容器构建层，不能用 CLI 的检查结果替代 Web 进程的运行时确认。

--ignore-platform-req=ext-foo 可以用于一次性的诊断或明确知道后果的构建场景，范围比 --ignore-platform-reqs 小；后者会忽略 PHP、扩展等全部平台要求。它们都不是修复方案。Composer 官方也提醒，模拟平台或忽略要求可能让安装通过，却把缺失能力留到生产运行时才暴露。

常见问题

为什么 php -v 显示满足，Composer 仍然报错？

可能检查的是不同 PHP 二进制，或者缺少某个 ext-* 扩展。先看 command -v php、php -m，再执行 composer check-platform-reqs。

config.platform 能不能直接删掉？

不要盲删。它可能用于模拟部署目标；先确认项目是否依赖这个求解边界，并在真实部署机运行平台检查，再决定保留、修正还是移除。

check-platform-reqs 和 install 有什么区别？

install 负责按声明或 lock 文件安装依赖；check-platform-reqs 负责检查已安装依赖与真实 PHP/扩展是否匹配，适合放在部署后的检查环节。