PHP Composer 怎样解释 platform 配置对依赖解析的影响

PHP Composer 的 config.platform 可以把依赖解析“放到”一个指定的 PHP 或扩展版本上。它适合在开发机和生产机版本不同、但项目必须按生产环境解析依赖的场景；它改变的是 Composer 的判断依据，不会升级本机 PHP，也不会自动安装缺失扩展。

官方文档：https://getcomposer.org/doc/06-config.md#platform

最容易记住的边界是：config.platform 负责“按哪个平台解析”，check-platform-reqs 负责“真实机器是否满足”。前者可以让锁文件更贴近目标环境，后者必须在部署阶段检查实际 PHP 和扩展。

• 解析层：Composer 把配置里的 PHP、ext-* 当作虚拟平台包参与版本约束判断。
• 运行层：应用启动时仍使用机器上的真实 PHP 和扩展。
• 交付层：锁文件安装后，用真实平台检查把“解析成功”和“能运行”分开确认。

platform 配置到底改变了什么

Composer 解析依赖时，会读取根项目与依赖包的 require 约束，例如 php: ^8.1 或 ext-mbstring: *。配置 config.platform 后，Composer 会用配置中的版本和扩展集合模拟目标平台，再决定哪些依赖版本可被选中。

例如开发机运行 PHP 8.3，而线上仍是 PHP 8.1，可以在项目里写成下面的最小配置。JSON 不支持注释，因此字段含义放在代码块外解释。

{
  "require": {
    "php": "^8.1",
    "ext-mbstring": "*"
  },
  "config": {
    "platform": {
      "php": "8.1.0",
      "ext-mbstring": "8.1.0"
    }
  }
}

这里的 php 版本是解析器看到的目标版本；ext-mbstring 表示依赖解析时把该扩展视为已提供。它不会修改当前命令行里的 php -v，也不会替你加载扩展。配置值应当描述真实部署目标，而不是为了让某个依赖暂时通过而随意填写。

为什么本地能更新，生产却可能启动失败

这个问题通常发生在两台机器看到的“平台”不同：开发机的 Composer 可能按 8.1 解析出一组依赖，但生产机实际是 PHP 8.0，或者缺少某个扩展。只要解析阶段被虚拟平台满足，composer update 或 install 就可能正常完成；应用真正运行时仍要接受生产机的限制。

发布流程中可以把锁文件安装和真实平台复核分成两步。命令里的注释解释了各自用途：

# 按 composer.lock 安装，保持依赖版本与解析结果一致
composer install --no-dev --prefer-dist

# 忽略 config.platform，检查当前 PHP 与已安装扩展是否满足依赖
composer check-platform-reqs --no-dev

官方命令说明明确指出，check-platform-reqs 会忽略 config.platform，检查安装包要求的真实 PHP 与扩展版本。因此它适合放在部署机或发布流水线，而不是用来替代依赖解析。

platform-check 和忽略参数怎样区分

Composer 还会生成运行时平台检查文件。config.platform-check 默认只检查 PHP；设置为 true 时也检查扩展，设置为 false 则不生成并要求 platform_check.php。如果生产环境可能和解析目标不一致，关闭它只会减少一道保护，不会修复版本或扩展缺失。

--ignore-platform-reqs 也不是 platform 配置的替代品。它会跳过 PHP、扩展等平台要求，适合极少数明确隔离的安装场景；如果项目本来就需要该扩展，长期忽略会把问题推迟到运行时。更稳妥的做法是修正目标平台、安装缺失扩展，或调整真正不兼容的依赖约束。

# 只在明确知道后果时临时忽略某一个扩展要求
composer install --ignore-platform-req=ext-example

# 查看某个 PHP 版本为何不能满足当前依赖
composer prohibits php 8.1

一张表记住判断顺序

如果只记一条发布经验：让 config.platform 对齐真实目标环境，然后把 check-platform-reqs 作为部署检查。遇到解析成功但生产失败，先比较“虚拟平台”和“真实平台”，不要先用忽略参数掩盖冲突。

常见问题

config.platform 会改变服务器的 PHP 版本吗？

不会。它只是 Composer 的解析配置，服务器仍运行自己的 PHP 二进制和扩展。

为什么配置了 platform 还要运行 check-platform-reqs？

因为前者可以模拟目标平台，后者专门忽略这层模拟并读取当前机器的真实平台，两者回答的问题不同。

platform-check 设置为 false 能解决缺扩展吗？

不能。它只关闭 Composer 生成的运行时检查，缺失扩展仍可能在业务代码执行时暴露。