Composer platform config部署环境 PHP 版本不一致怎样提前发现为什么结果为空或不符合预期

Composer 里配置了 config.platform.php 后，依赖解析器会按这个版本判断包是否可用，但部署服务器仍然运行自己的 PHP。于是开发机上看到的依赖结果可能“为空”、少了一些包，或锁文件能安装却在目标环境不符合预期。排查的关键不是反复改版本号，而是先分开看模拟平台、项目声明和真实解释器。

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

先看 composer.json 中的模拟平台，再在目标 PHP 上运行 check-platform-reqs。前者解释“为什么这样解析”，后者回答“部署机器是否真的满足”。

结果为空时先确认是谁在做判断

假设项目希望兼容 PHP 8.2，开发机却是 PHP 8.3。下面的配置把依赖解析固定在 8.2.0；它是解析基线，不会把 PHP 8.3 变成 PHP 8.2，也不会替部署机安装扩展。

{
  "require": {
    "php": ">=8.2 

这里的 JSON 必须保持严格格式，因此不在代码块里插入注释。require.php 是项目对运行环境的声明，config.platform.php 是 Composer 解依赖时使用的假定值。两者都没有声明“当前服务器真实安装了哪个 PHP”。

# 查看 platform 配置来自哪个文件，避免误读全局配置
composer config platform.php --source

# 查看当前项目声明的 PHP 约束，确认它没有被空值或错误范围替代
composer show --platform

如果依赖列表为空或和预期不一致，先检查命令所在目录、COMPOSER 环境变量以及项目是否真的读取了这份 composer.json。再查看 composer.lock 是否由同一平台基线生成。不要把“解析器接受了某个版本”理解成“部署解释器已经切换”。

用依赖诊断解释“为什么没有结果”

当某个包没有被选中，单看结果列表往往不够。更有效的做法是把目标 PHP 版本当成一个待解释的约束，查看哪个依赖阻止它。例如下面的命令只用于定位约束来源，不会修改锁文件：

# 解释为什么当前依赖集合不能接受 PHP 8.3
composer prohibits php 8.3 --tree

# 只查看当前锁文件中的包，避免把尚未安装的候选混进判断
composer show --locked --name-only

如果 prohibits 给出冲突链，说明“空结果”其实是约束筛选后的结果；如果没有包名，优先回到项目目录、锁文件和 platform 配置来源排查。更改 config.platform.php 后需要在受控环境重新解析并审阅锁文件，不能只改 JSON 就假定依赖集合已经变化。

对部署来说，通常应提交经过审阅的锁文件，并在目标环境使用 install。生产机临时执行 update 会重新求解依赖，使“本地看见的结果”和“部署得到的结果”失去同一输入。

在真实 PHP 中检查锁文件要求

Composer 官方文档明确区分了平台模拟和实际平台检查。部署阶段可以把检查放在安装前后，并让失败退出状态阻断后续发布：

#!/usr/bin/env bash
# 任一检查失败都停止当前部署，避免继续发布不兼容的 vendor
set -euo pipefail

# --lock 只按锁文件检查；--no-dev 对生产安装排除开发依赖
composer check-platform-reqs --lock --no-dev

# 只安装已提交的依赖集合，不在生产机重新求解版本
composer install --no-dev --no-interaction --prefer-dist

# 安装后按真实 PHP 与扩展再次确认实际运行平台
composer check-platform-reqs --no-dev

check-platform-reqs 会忽略 config.platform，检查运行命令的真实 PHP 和扩展。因此 CLI 检查成功只代表这个 CLI 解释器满足要求；如果 PHP-FPM 使用另一套镜像、配置或扩展，还要在相同运行环境中执行检查。本文代码是读者可复现的写法，没有在本机运行 Composer，也没有伪造通过输出。

按差异类型修复，而不是用忽略参数遮住问题

--ignore-platform-reqs 只能绕过安装阶段的要求，不能修复运行时缺少扩展或不兼容语法。把 config.platform.php 写得过高也会让解析结果失去生产参考价值。更稳妥的记录包括 PHP 与 Composer 版本、扩展清单、配置来源、锁文件提交号和检查退出状态。

常见疑问

platform.php 能替代 require.php 吗？不能。前者是解析时的模拟平台，后者是项目对运行环境的公开契约；只配置前者会让项目缺少最低版本声明。

把 platform.php 改成生产版本就够了吗？不够。它只能让依赖解析更接近目标，不能证明生产 PHP、扩展、FPM 配置和外部二进制都已满足，仍应运行真实平台检查和业务测试。

官方配置和命令文档在哪里？https://getcomposer.org/doc/06-config.md#platform 与 https://getcomposer.org/doc/03-cli.md#check-platform-reqs。