PHP Composer 怎样按平台条件锁定依赖

PHP Composer 锁依赖时，最容易忽略的不是版本号，而是“解析器以哪台机器的平台为准”。本地 PHP 8.3 执行 composer update，可能选出只支持 PHP 8.2 的包；部署机若仍是 PHP 8.1，composer install 就会在平台检查阶段失败。更稳妥的做法是：把部署目标写进 config.platform 参与求解，再用生产机真实环境执行 check-platform-reqs。

官方文档：https://getcomposer.org/doc/articles/composer-platform-dependencies.md

下面只讨论 PHP、扩展和 Composer API 这类平台包，以及它们如何影响 composer.lock；不把平台约束当成运行时环境替代品。

先把平台包和普通依赖分开

Composer 会把当前环境提供的 PHP、ext-* 扩展、lib-* 库和 Composer API 暴露成虚拟平台包。它们不是要下载到 vendor/ 的代码，但普通包可以在 require 中声明它们，例如 "php": ">=8.1" 或 "ext-mbstring": "*"。

先看解析器眼中的平台集合，能避免把“本机已装扩展”与“线上也有扩展”混为一谈：

# 查看 Composer 当前可见的 PHP、扩展和库平台包
composer show --platform

# 查看项目声明与解析结果，确认平台约束是否参与求解
composer why-not php 8.1

show --platform 是观察入口；why-not 用来解释某个平台版本为什么不能满足当前依赖。它们都不会替你修改锁文件。

用 config.platform 把部署目标写进求解边界

如果开发机与生产机的 PHP 版本不同，可以在项目的 composer.json 中声明目标平台。下面的配置表示：依赖解析按 PHP 8.1 和已存在的 mbstring 扩展来选择版本。

{
  "require": {
    "php": ">=8.1",
    "symfony/console": "^6.4"
  },
  "config": {
    "platform": {
      "php": "8.1.0",
      "ext-mbstring": "*"
    },
    "platform-check": true
  }
}

这是严格 JSON，因此不在代码块里加入注释；require.php 是项目的最低要求，config.platform.php 是求解时模拟的目标版本，二者用途不同。平台版本设置得比生产机新，会让解析结果再次越过生产边界；设置得过旧，则可能错过项目实际允许的版本。

扩展也可以写成具体版本，但只有确实需要版本下限时才这么做。对大多数扩展，声明存在性更清楚；不要为了让本地解析通过，随手写成一个线上并不存在的扩展版本。

只在目标平台下更新一次，再交付 lock 文件

config.platform 改动后，必须重新运行 update 让求解器重算依赖并写入锁文件。团队协作和部署环境使用 install 时，Composer 会读取锁文件里的精确版本，不应在生产机临时执行完整 update。

# 读取 config.platform 重新求解，并更新 composer.lock
composer update --with-all-dependencies

# 在构建或部署机按锁文件安装，不重新选择版本
composer install --no-dev --prefer-dist

# 把 composer.json 和 composer.lock 一起纳入代码交付
git add composer.json composer.lock

这里的关键不是命令参数越多越好，而是更新动作发生在已经写好目标平台的项目状态上。若只是改了 composer.json 却继续沿用旧锁文件，读者看到的配置和实际交付结果就会脱节。

部署前用真实平台做最后一道判断

config.platform 是“求解假设”，而生产机的 PHP 二进制和扩展才是“运行事实”。因此部署阶段应执行：

# 忽略 config.platform，检查当前机器真实的 PHP 与扩展
composer check-platform-reqs --no-dev

# 只根据锁文件中的包要求检查，适合已经准备好 lock 的构建阶段
composer check-platform-reqs --lock --no-dev

如果这个检查报告缺少 ext-intl 或 PHP 版本过低，优先修复镜像、主机或扩展安装，而不是给 install 加上 --ignore-platform-reqs。忽略参数只会跳过当前求解或安装时的约束，不能让缺失的运行能力凭空出现。

Composer 还可能在自动加载器引导阶段生成 platform_check.php。保留默认检查通常更安全；即使项目因特殊部署原因关闭它，也应该把 check-platform-reqs 放进构建门禁，否则问题会推迟到业务请求才暴露。

遇到平台冲突时按这张清单处理

• 先运行 composer show --platform，记录本机真正提供的 PHP 和扩展。
• 检查 composer.json 中的 require.php、ext-* 与 config.platform 是否表达同一个部署目标。
• 修改目标平台后重新 composer update，把新的 composer.lock 一并提交。
• 部署时使用 composer install，再执行 composer check-platform-reqs --no-dev。
• 只有在确认依赖实际不需要某项平台能力时，才讨论精确的忽略参数；不要把全量忽略当作修复。

一句话总结：config.platform 负责把生产目标带入依赖求解，composer.lock 负责交付确定版本，check-platform-reqs 负责揭示生产机真实条件。三者配合，才能避免“本地能更新、线上装不上”反复出现。

相关问题

config.platform 会安装对应版本的 PHP 吗？

不会。它只影响 Composer 的依赖解析，PHP 本身和扩展仍需由运行环境提供。

生产机可以执行 composer update 吗？

一般不建议。项目应在有明确目标平台的构建环境生成锁文件，生产机按锁文件执行 install。

为什么设置了 config.platform 仍然启动失败？

因为设置只代表求解假设；生产 PHP、扩展或系统库仍可能不满足锁定包的实际要求，应查看 check-platform-reqs 的结果。