Composer如何用platform配置_Composer platform平台约束教程【必看】-composer-PHP中文网

platform是composer在依赖解析阶段模拟php环境的配置，只影响composer update选包逻辑，不改变php -v输出或运行时行为，需正确配置在composer.json的config.platform下。

composer如何用platform配置_composer platform平台约束教程【必看】

platform 是什么？它根本不是“切换 PHP 版本”的开关

platform 配置不会改你本地的 php -v 输出，也不会让 composer install 自动调用别的 PHP 二进制。它只干一件事：在依赖解析阶段，**假装当前环境是某个 PHP 版本+扩展组合**，从而影响 composer update 挑包的逻辑。

常见错误现象：
– 本地 PHP 是 8.3，但生产是 8.1，没配 platform，结果装了要求 php: ^8.2 的包，上线直接 Fatal error: Uncaught Error: Undefined constant "PHP_VERSION_ID"
– 配了 "platform": {"php": "8.1.0"}，但 ext-sodium 在目标服务器根本没启用，运行时报 Class 'SodiumException' not found

platform 只影响 composer.lock 生成和依赖版本选择，不干预运行时
它不检查扩展是否真实存在，只看你有没有在 platform 里声明；没写，就当它不存在
如果你项目 require 里写了 "php": "^8.1"，那 platform 设成 "8.0.0" 会导致 composer update 报错——因为约束冲突

怎么写才生效？位置、格式、版本号全得对

必须写在 composer.json 的 config 对象下，键名就是 platform，值是一个对象，不能是字符串，也不能嵌套错层级。

正确示例：

{
  "require": { "monolog/monolog": "^3.0" },
  "config": {
    "platform": {
      "php": "8.1.25",
      "ext-mbstring": "*",
      "ext-openssl": "*",
      "ext-curl": "*"
    }
  }
}

别写成 "platform.php" 或 "php-platform" —— 这些键名完全无效
版本号建议写具体小版本（如 "8.1.25"），避免 "^8.1" 被解析成 8.1.99 导致误判
扩展要显式列出，"*" 表示“假定已启用”，不是“自动检测”；没列的扩展，Composer 就当它不可用
改完后务必删掉 composer.lock 和 vendor/，否则旧锁文件会缓存之前解析结果，platform 形同虚设

什么时候该用 platform-check-file？别乱配

platform-check-file 是 Composer 2.5+ 的高级选项，只适合 CI/CD 中「环境混乱但目标明确」的场景，比如 GitHub Actions 里用 shivammathur/setup-php 安装了 PHP 8.1，但宿主机 php -v 是 8.0 —— 此时你想跳过真实环境检测，靠静态快照驱动。

Composer

Composer 是 PHP 生态常用依赖管理工具，用于安装框架、组件和项目依赖。

下载

但它有两个硬性前提：

必须同时设置 "platform-check": false，否则 Composer 先跑真实检测，失败就退出，根本不会读你的文件
文件路径必须是相对 composer.json 的合法路径，如 ./ci/platform.json；不能含 ~ 或环境变量
文件内容必须是严格 JSON：{"php": "8.1.22", "ext-curl": true, "ext-json": true}，键名大小写敏感，ext- 前缀缺一不可

注意：platform-check-file 不解决扩展缺失问题，它只是绕过检测。如果 ext-gd 真没装，应用照样崩。