PHP Composer 怎样锁定平台 PHP 版本

如果开发机是 PHP 8.4，而线上仍然运行 PHP 8.2，Composer 可能在本地解析出一组线上无法安装或运行的依赖。解决办法是在项目的 composer.json 中锁定 Composer 看到的目标平台版本，而不是把本机 PHP 降级。

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

最小配置如下：

{
  "require": {
    "monolog/monolog": "^3.0"
  },
  "config": {
    "platform": {
      "php": "8.2.0"
    }
  }
}

这里的 8.2.0 是依赖解析时使用的目标版本。它会阻止 Composer 选择要求更高 PHP 版本的包，但不会改变当前命令真正运行的 PHP。

最小配方：在项目配置里锁定 PHP 平台

推荐把平台约束提交到项目仓库，让开发机、CI 和部署脚本共享同一个依赖解析边界。也可以使用命令写入配置：

# 把项目的依赖解析平台固定为 PHP 8.2
composer config platform.php 8.2.0

# 重新解析并写入锁文件，确保锁文件反映新的平台边界
composer update

如果只想调整配置并保留现有锁文件，可以先提交 composer.json，再由 CI 或专门的依赖更新任务执行 composer update。不要把 --ignore-platform-reqs 当成长期方案，它会掩盖真实的版本或扩展缺口。

关键判断：模拟平台不等于运行平台

config.platform.php 只影响 Composer 的依赖求解。比如本机是 PHP 8.4，但配置了 8.2，Composer 会按 PHP 8.2 判断包的兼容性；脚本执行时仍然使用本机的 PHP 8.4。

先查看 Composer 当前识别到的平台包：

# 查看本机真实的 PHP 与扩展平台包
composer show --platform

# 只检查当前机器能否满足已安装依赖的真实要求
composer check-platform-reqs

第一条命令用于观察解析环境，第二条命令用于部署前检查真实环境。两者结果不同并不一定是错误：前者可能包含 platform.php 的模拟值，后者应反映当前 PHP 二进制和已加载扩展。

变体：同时锁定扩展版本或隐藏本地扩展

平台配置也能描述扩展要求，例如：

{
  "config": {
    "platform": {
      "php": "8.2.0",
      "ext-mbstring": "8.2.0"
    }
  }
}

只有在团队确实需要模拟目标扩展版本时才这样做。若本机装有某扩展、生产机没有，可以把对应平台包设为 false，让解析阶段不要误以为生产具备它；但更稳妥的做法是修正生产环境，而不是长期隐藏依赖。

容易踩坑的边界

• 锁定版本不会降级 PHP：它改变的是 Composer 的判断，不会替换 CLI、FPM 或容器里的 PHP。
• 锁定后仍要检查真实环境：部署阶段保留 composer check-platform-reqs，避免把本地模拟值带到线上。
• 升级 PHP 时同步审阅锁文件：先修改 platform.php，再有计划地更新依赖，不要只删除 composer.lock。
• 留意自动生成的 platform_check.php：Composer 默认会在自动加载入口检查运行时平台；不要为了绕过问题而关闭它，除非你已经有等价的部署检查。

一张表记住正确用法

常见问题

问：配置了 PHP 8.2，为什么本机仍显示 PHP 8.4？
答：这是预期行为。平台配置只服务于依赖求解，本机的 PHP 版本由实际命令解释器决定。

问：改完 platform.php 后是否必须立刻删除 composer.lock？
答：不建议直接删除。先按变更计划运行依赖更新并审阅锁文件差异，再让 CI 和部署环境执行真实平台检查。

总结：把目标 PHP 写入 config.platform.php，用它约束依赖解析；用 composer check-platform-reqs 检查真实部署环境；升级 PHP 或扩展时同步审阅锁文件和运行时平台检查。