Composer怎么设置项目的PHP版本约束_Composer.json配置平台版本【规范】

platform 配置仅在本地 composer install/update 时生效，用于模拟目标 php 环境以控制依赖安装，但不影响实际运行环境；必须置于 config.platform 下且值为具体版本号（如 “8.1.10”），不可用约束语法；require.php 才是项目真实最低 php 要求，决定兼容性与依赖检查，platform 不得低于 require 声明的版本。

composer.json 里 platform 配置到底管不管用

它只在本地 composer install 或 composer update 时起作用，**不会影响远程构建或生产环境 PHP 版本**。本质是让 Composer 假装当前运行环境是某个 PHP 版本，从而决定能装哪些包（比如 phpunit/phpunit 9.x 要求 PHP >=7.3，你本地是 8.1，但设了 "php": "7.4"，Composer 就不会选 9.x）。

常见错误现象：composer install 成功，但部署到服务器后报 ParseError: syntax error, unexpected Token "String" —— 因为 platform 欺骗了依赖解析，却没约束实际运行环境。

• 仅用于解决“本地开发环境 PHP 版本高于目标部署环境”时的依赖兼容问题
• 必须配合真实部署环境验证，不能只信 platform
• 如果项目要跑在 PHP 8.0+，就别硬设成 "php": "7.4"，否则可能错过真正适配新版的语言特性支持

怎么写 platform 才不翻车

写法很简单，但容易漏掉关键点：它必须放在 config 下，且只接受字符串值（不是数组、不是布尔）。

正确示例：

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

{     "config": {         "platform": {             "php": "8.1.10"         }     } }

错误写法包括："php": "^8.1"（版本约束语法无效）、"platform": "php:8.1"（格式错）、"platform": {"php": 8.1}（数字类型被当成 Float，Composer 会忽略）。

• platform.php 值必须是具体版本号，如 "8.1.10" 或 "8.2"，不支持 ~、^、>= 等运算符
• 如果同时约束扩展（如 ext-mbstring），必须写全名 + 版本，如 "ext-mbstring": "8.1.10"，空字符串或 "*" 不生效
• 设了 platform 后，composer show php 显示的是你写的值，不是系统真实版本 —— 别靠这个判断运行时环境

为什么 require 里的 php 字段比 platform 更重要

require.php 是项目对 PHP 的**真实最低要求**，会被 Packagist 收录、被其他包依赖检查、被 CI 工具读取。它决定“这个包能不能被别人 require”，而 platform 只决定“我本地装不装得下”。

典型误用：只配 platform 却没写 require.php，结果别人 composer require your/package 时，Composer 完全不知道该检查什么 PHP 版本，直接装上就跑崩。

• 必须在 require 中声明底线："php": "^8.1"（推荐用 ^，兼顾小版本更新）
• require.php 和 platform.php 可以不同，但 platform 不应低于 require 声明的最低版本，否则 Composer 可能选到不兼容的依赖
• CI 脚本里建议加一行 php -v | head -n1，和 require.php 对照，比只信 platform 可靠得多

PHP 主版本升级时最常踩的坑

从 PHP 7.4 升到 8.0/8.1，光改 platform 和 require 不够，很多包在主版本跳变时行为突变 —— 尤其是依赖反射、错误处理或类型推导的库。

比如 doctrine/orm 2.12 要求 PHP >=8.1，但如果你 platform 还锁着 "php": "7.4"，Composer 可能给你装个 2.11，结果运行时报 TypeError: Return value of ... must be of the type string, NULL returned —— 因为底层用了 PHP 8.0 的联合类型，但代码没适配。

• 升级前先清掉 vendor 和 composer.lock，再跑 composer update --with-all-dependencies
• 关注包的 changelog 里 “PHP 8.x compatibility” 条目，别只看 composer.json 的 require.php
• platform 是临时拐杖，不是长期方案；上线前务必在真实 PHP 版本下跑一遍测试，而不是只信本地 composer install 成功

真正卡住人的从来不是怎么写那几行 json，而是搞不清 platform 是给 Composer 看的“假话”，而 require.php 是给世界说的“实话”——这两者对不上，问题就藏在部署后的第一个请求里。