Composer如何配置包的最低 PHP 版本要求_在 require 中定义【环境兼容】

Composer 不允许在 require 字段中声明 PHP 版本要求，因 require 仅用于包依赖而非环境约束；真正生效的是顶层 “php” 字段（运行时校验）和 config.platform.php（构建时依赖解析锁定）。

在 Composer 里，把 PHP 版本要求写在 require 字段里——这是个流传甚广的误解，也是不少项目上线后，因为环境不匹配而突然报错的罪魁祸首之一。

为什么 require 里写 "php": "^8.1" 会失效

道理其实很简单：require 这个字段，是专门用来声明「项目所依赖的其他 Composer 包」的，它管不了运行环境。所以，即便你把它写进去，Composer 在安装时也根本不会去校验 PHP 版本，更不会阻止你在低版本的 PHP 上执行 composer install。

更棘手的情况是：某些依赖包的自动加载器（比如 vendor/autoload.php）可能在 PHP 7.4 环境下就直接抛出致命错误了，而此时 Composer 早已“假装安装成功”，留下一堆烂摊子。

• 关键在于，require 里的 "php" 条目会被 Composer 直接忽略（除非配合 config.platform.php 使用，但那完全是另一套逻辑）。
• 真正能起作用的，其实是 config.platform.php 或者根级别的 php 字段（下文会详细讲）。
• 这个问题在 CI/CD 流水线或者一些老旧的服务器上，最容易暴露出来。

正确方式：用 config.platform.php 锁定构建时的 PHP 版本

这个配置项的作用很明确：它告诉 Composer，“请把当前项目当成运行在指定 PHP 版本的环境里，并以此为标准来解析所有依赖关系”。这直接影响了 composer install 和 composer update 时对包版本的选择逻辑——例如，它会自动跳过那些只支持 PHP 8.2 及以上版本的包。

立即学习“PHP免费学习笔记（深入）”；

具体操作就是在 composer.json 的 config 部分添加：

{
    "config": {
        "platform": {
            "php": "8.1.0"
        }
    }
}

• 这里有个细节：值必须是具体的版本号（比如 "8.1.0"），不能使用波浪线或脱字符范围（写 "^8.1" 会直接报错）。
• 它只控制依赖解析过程，并不会替代运行时的 PHP 版本检查。
• 这个配置在需要稳定依赖解析的场景下特别有用，比如 CI 构建、Docker 多阶段构建等。

运行时强制校验：靠 require 顶层的 php 字段

这才是真正能让 Composer 在 install 或 update 阶段就“拍桌子”报错的字段。它必须放在 composer.json 的最外层，和 require 属于同级关系：

{
    "require": {
        "monolog/monolog": "^2.0"
    },
    "require-dev": { ... },
    "php": ">=8.1.0"
}

• Composer 会检查当前执行 composer 命令的 PHP 环境版本，看是否满足这个条件。
• 如果不满足，它会直接中断操作，并给出类似 Your PHP version (7.4.33) does not satisfy that requirement. 的明确提示。
• 需要警惕的是：它只校验你执行 Composer 命令时所在的 PHP 环境，并不校验最终部署的目标服务器。因此，在部署脚本里做二次检查，依然是必不可少的步骤。

容易被忽略的组合陷阱：平台 + 运行时 + 实际部署

很多人只配置了根级的 php 字段，却忽略了 config.platform.php 对依赖版本选择的深远影响。结果就是，在本地 PHP 8.2 环境下开发时，安装了一个仅支持 8.2 的扩展包，等到部署到 PHP 8.1 的服务器上，运行时直接报出 undefined function，让人措手不及。

• 比较稳妥的做法是组合使用："php": ">=8.1.0"（用于运行时拦截） + "config.platform.php": "8.1.0"（用于依赖锁定）。
• 在 Dockerfile 里，务必显式声明基础镜像版本，比如 FROM php:8.1-cli，不要依赖基础镜像的默认版本。
• 随时可以用 composer show --platform 命令，来查看当前生效的平台配置情况。