PHP Composer 平台配置怎样锁定运行时版本

我在把 PHP 项目从本地环境交给 CI 和生产服务器时，最容易混淆的一点就是：config.platform 能让 Composer 按指定的 PHP 平台解析依赖，但它不会改变当前机器真正运行的 PHP。要让“依赖怎么选”和“服务器能不能跑”都可控，应该把目标平台写进 composer.json，提交匹配的 composer.lock，部署时再用真实 PHP 做平台检查。

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

下面以 PHP Composer 平台配置为主线，把升级或迁移时最容易漏掉的几个环节拆开。文中的配图是原创静态说明图，用来解释关系，不是官网、终端或编辑器截图。

先把“目标版本”和“当前版本”分开

Composer 把 PHP 和扩展视为平台包。项目在执行依赖解析时，会把当前可见的平台需求拿来和包的 require 条件比较。config.platform 则提供了一套可以“模拟”的平台版本，例如把目标 PHP 写成 8.2.0，让本地 PHP 8.3 也按 PHP 8.2 的约束选择依赖。

这项配置解决的是“依赖解析基线”问题，不是 PHP 运行时切换器。它不会安装 PHP 8.2，也不会让扩展在服务器上凭空出现。生产机仍然要有真实的 PHP 二进制和所需扩展。

composer.json 里应该怎样声明平台

最小写法是把平台配置放到 config.platform。如果项目只受 PHP 版本约束，可以先声明 php；如果依赖还要求特定扩展，则把实际部署必须具备的扩展也写出来。扩展版本要以项目和服务器的真实约束为准，不要为了让解析通过而随意填一个更高版本。

{
  "require": {
    "php": "^8.2",
    "monolog/monolog": "^3.0"
  },
  "config": {
    "platform": {
      "php": "8.2.0",
      "ext-json": "8.2.0"
    },
    "platform-check": true
  }
}

上面的 JSON 必须保持有效，所以没有在代码块里插入注释。require.php 表达项目允许的版本范围，config.platform.php 表达依赖解析时采用的目标平台；两者不是同一个字段，前者不能替代后者。platform-check 保持开启时，Composer 生成的自动加载入口还会对运行中的 PHP 平台做相应检查。

迁移时最容易踩的三个坑

我个人在迁移项目时会把第二行当成独立的部署门禁：平台配置负责“怎么选包”，真实检查负责“这台机器能不能运行”。两者合并成一个结论，反而容易把问题推迟到线上。

改完平台配置后怎样更新锁文件

如果 composer.lock 已经存在，部署环境通常使用 composer install 来复现锁定结果。平台目标发生变化时，开发分支需要重新计算依赖，让锁文件反映新的约束；不要只改 JSON 后把旧锁文件继续当成新平台的结果。

# 先确认 Composer 看到的目标平台配置
composer config platform.php

# 在依赖调整分支重新求解，锁文件会随依赖结果更新
composer update

# CI 或生产按已经提交的锁文件安装，不主动重新选版本
composer install --no-dev --prefer-dist --no-interaction

这里的 update 是重新求解动作，可能带来多个间接依赖变化，应该放在有审查和回归测试的分支完成。生产部署则尽量使用锁文件安装，避免每次发布都因为仓库新版本而得到不同结果。

部署阶段要检查真实 PHP 和扩展

Composer 官方把 check-platform-reqs 设计为真实平台检查命令。它会检查当前 PHP 进程以及扩展是否满足已安装包的要求，并且会忽略 config.platform，这样才能知道服务器本身是否真的具备运行条件。

# 只检查锁文件里的生产依赖，避免把开发依赖带进部署门禁
composer check-platform-reqs --lock --no-dev

# 检查失败时停止发布，而不是继续启动应用
if [ "$?" -ne 0 ]; then
  # 真实平台不满足依赖时，交给发布系统中止本次部署
  echo "PHP platform requirements are not satisfied" >&2
  exit 1
fi

如果使用自动加载器的运行时平台检查，也要把它视为最后一道保护，而不是替代部署检查。生产环境缺扩展时，越早在构建或发布阶段失败，越容易定位到镜像、主机或扩展安装问题。

为什么不建议长期使用 --ignore-platform-reqs

--ignore-platform-reqs 的作用是跳过平台要求，它适合临时诊断某些依赖解析问题，不适合作为“锁定运行时版本”的方案。它可能让安装阶段继续执行，却把缺 PHP 版本、缺扩展或扩展版本过低的问题留到应用启动时。

如果 CI 里已经出现这个参数，我会先问三个问题：目标 PHP 是否与生产一致；镜像是否安装了 ext-*；锁文件是否在平台配置变更后重新生成。能修正环境或约束，就不要用忽略参数掩盖差异。

给 PHP 项目的迁移清单

1. 在 composer.json 里写清生产目标 PHP，必要时写清扩展平台。
2. 确认 require.php 的范围没有和目标平台互相矛盾。
3. 在开发或升级分支运行依赖更新，审查并提交新的 composer.lock。
4. CI 使用锁文件安装，并在发布前运行 composer check-platform-reqs --lock --no-dev。
5. 检查容器或主机的 PHP 二进制、扩展和 CLI 版本，确认和 Web 进程不是两套环境。
6. 清理长期存在的 --ignore-platform-reqs，把临时诊断参数从正式流水线移除。

这样配置后，Composer 的“选择依赖”和服务器的“能够运行”各自有明确责任。平台配置并不是把本地 PHP 变成生产 PHP，而是把团队对目标运行时的假设写成可提交、可复用的依赖解析输入。

常见问题

config.platform 会改变 PHP 的实际版本吗？

不会。它只影响 Composer 判断依赖是否满足以及如何求解，当前 PHP 进程仍由本机或服务器安装的运行时决定。

为什么已经设置 platform 还要跑 check-platform-reqs？

因为前者是虚拟平台，后者检查真实 PHP 和扩展。部署时两者缺一不可。

只提交 composer.json、不提交 composer.lock 可以吗？

应用项目通常不应这样做。没有锁文件，安装时可能重新选择间接依赖，迁移结果也更难复现。