PHP Composer 平台依赖约束的迁移检查

PHP 项目从旧版本迁移到新环境时，最容易混淆的是“Composer 按哪个平台解析依赖”和“生产 PHP 进程到底具备什么条件”。config.platform 可以让解析器按目标 PHP 或扩展版本计算依赖，但它不会替服务器安装扩展，也不会改变正在执行 Composer 的 PHP。正式迁移时，应先用它生成合适的依赖解，再用真实环境检查锁定依赖。

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

先分清模拟平台和真实运行环境

Composer 把 PHP、ext-* 扩展、lib-* 系统库以及 Composer API 视为平台包。项目在 require 中声明 php 或 ext-mbstring 后，Composer 会把正在执行命令的环境作为候选平台参与解析。

迁移时如果构建机还是 PHP 8.1，而生产准备升级到 PHP 8.3，可以在根项目的 config.platform 中描述目标版本。这个配置只改变“哪些包版本可被选中”的判断，不会伪造服务器上的二进制能力。也就是说，解析成功只能说明依赖组合在目标约束下成立，还不能证明当前机器加载了对应扩展。

用 composer.json 描述迁移目标

假设项目要迁移到 PHP 8.3，并且运行时必须有 mbstring。根项目可以写出明确的平台约束：

{
  "require": {
    "php": ">=8.3 

上面的 require 是项目对运行平台的声明，config.platform 是依赖解析时使用的目标平台描述。扩展版本并不应随意填写一个看起来“新”的数字；如果只需要扩展存在，可以使用项目真正需要的约束表达式，并在目标环境用实际检查确认。

修改平台后重新生成锁文件，让锁定结果反映迁移目标：

# 先确认根项目的 platform 配置，再按目标平台重新计算锁定依赖
composer update --with-all-dependencies

# 只安装锁文件中的结果，不重新选择版本
composer install --no-interaction --prefer-dist

如果只是想查看当前 Composer 进程能看到哪些平台包，可以使用：

# 列出当前真实 PHP 进程报告的 PHP、扩展和系统库平台包
composer show --platform

迁移验收要用 check-platform-reqs

真正部署前，要在与应用相同的 PHP 进程和扩展环境中执行检查：

# 读取已安装依赖的要求，并检查当前 PHP 与扩展是否满足
composer check-platform-reqs --no-dev

# 需要给流水线消费时输出 JSON，失败仍应让流水线停止
composer check-platform-reqs --no-dev --format=json

这个命令与安装或更新不同，会忽略 config.platform，直接检查真实平台包。因此本地能通过解析、生产检查却提示缺少 ext-mbstring 时，问题不是锁文件“突然失效”，而是生产 PHP 没有加载必需扩展。不要用 --ignore-platform-reqs 把这个结果压掉；它只适合非常明确且临时的场景，不能作为迁移验收。

根据检查结果决定修复动作

如果构建机、CLI PHP、FPM PHP 和容器中的 PHP 不是同一套运行时，检查必须放到真正承载应用的环境中。否则你验证的可能只是 CLI 的扩展列表，应用请求却由另一套 FPM 配置处理。

常见问题

设置 config.platform 后，生产环境就不需要升级 PHP 了吗？

不是。它只影响 Composer 的依赖解析，不能安装 PHP、扩展或系统库；生产环境仍必须满足锁定依赖的真实平台要求。

为什么 composer install 能成功，check-platform-reqs 却失败？

安装阶段可能按 config.platform 解析，而检查命令会忽略该模拟配置并读取当前真实 PHP 与扩展。两者回答的是不同问题。

迁移时能不能一直使用 --ignore-platform-reqs？

不建议。它会跳过平台要求，可能把缺少扩展或 PHP 版本不兼容的问题推迟到运行时；应先修复目标环境，再用真实检查收口。