如何使用Composer模拟平台伪装配置技巧？

本文共计978个文字，预计阅读时间需要4分钟。

`config.platform 只在 ``

为什么 config.platform 在 composer install 时经常不生效

很多人改完 composer.json 的 "config": { "platform": { "php": "8.1.25" } } 就直接跑 composer install，结果还是报错：Your PHP version (7.4.33) does not satisfy that requirement。

这是因为：composer install 默认跳过依赖解析，直接读 composer.lock 并校验本地真实环境；而 config.platform 只参与 update 阶段的解析逻辑——锁文件里存的是上次解析结果，跟当前 platform 配置无关。

• 已存在 composer.lock 时，config.platform 对 install 完全无效
• 即使你本地 PHP 是 8.3，platform 设成 8.1，只要 lock 文件里记着一个要求 php: ^8.2 的包，install 就会失败
• 验证是否真起作用：删掉 vendor/ 和 composer.lock，再跑 composer update，然后看新生成的 lock 里选的包版本是否符合目标环境

怎么让 composer install 强制按目标平台装包

两种可靠方式，选其一：

• composer install --platform=php:8.1.25 --platform=ext-gd:8.1.25 --platform=ext-mbstring:8.1.25 —— --platform 优先级高于 config.platform，且在 install 和 update 两个阶段都生效
• 删掉 composer.lock 和 vendor/，再跑 composer update（确保 config.platform 已正确写入），生成新 lock 后再 install

注意：--platform=gd:1.0 无效，必须带 ext- 前缀；--platform=ext-mbstring 也不行，版本号不能省略（哪怕填 *）。

config.platform 写错位置或格式就等于没写

它不会报错，但会静默失效。常见错误包括：

• 把 "platform" 放在 composer.json 根级（同 require 并列），而不是嵌套在 "config" 对象里
• 写成 "platform.php"、"platforms" 或 "php-platform" —— 键名必须严格是 platform
• "platform": "8.1.25" —— 值必须是对象，不能是字符串
• 扩展名拼错，比如 "ext-gd.so"（应为 "ext-gd"）、"mbstring"（应为 "ext-mbstring"）

验证是否生效：运行 composer config --list | grep platform，看到带 (local) 标记的输出才算对。

platform-check 是个开关，不是可选项

"config": { "platform-check": false } 不是“增强兼容性”，而是关闭对本地真实扩展的校验——它只在 CI 构建时有用，比如 GitHub Actions 里用 shivammathur/setup-php 装了 PHP 8.1，但宿主机 php -v 是 8.0，此时不关 platform-check，Composer 会先检测失败并退出，根本不会读你的 platform 配置。

但它有代价：

• 关掉后，composer install 可能成功，但运行时因缺 ext-redis 直接崩溃
• platform-check 对 PHP 版本本身无影响（没法 runtime 检查解释器），只管扩展是否存在
• 如果只是想跳过某个扩展校验，用 --ignore-platform-req=ext-zip 比全局关更安全

真正容易被忽略的一点：platform 配置和 --platform 参数，都不解决运行时问题。你设了 "ext-sodium": "*"，不代表 random_bytes() 就能在生产环境调用成功——扩展必须真实安装并启用，否则 fatal error 照样发生。