<p>config.platform 是唯一靠谱的项目级 PHP 环境“模拟”方式，必须写在 composer.json 的 config 字段内，明确声明 PHP 版本及 ext-* 扩展，否则会导致线上崩；--ignore-platform-reqs 会跳过所有平台约束，应避免使用。</p>
直接说结论：config.platform 是唯一靠谱的项目级 PHP 环境“模拟”方式，它不改你本地 PHP，只让 Composer 在 install/update 时按目标环境选包——写错位置、漏配扩展、混用 --ignore-platform-reqs，都会导致线上崩。
config.platform 必须写在 composer.json 的 config 字段里
很多人把 platform 写成根级字段、塞进全局配置、或丢到 composer.json 外部文件，结果 CI 跑通本地报错，或者队友装的包版本不一致。原因很简单：config.platform 只在项目根目录的 composer.json 中、嵌套于 "config": { "platform": { } } 下才稳定生效。
- ✅ 正确位置：
composer.json同级于require和autoload，且必须是"config"的子字段 - ❌ 错误写法：
"platform": {}（根级）、"config.platform.php": "8.1"（不存在的字段）、composer config -g platform.php 8.1（污染全局） - 验证是否生效：运行
composer config --list | grep platform，看到带(local)标记才算对
只设 php 版本不够，扩展必须手动列全
config.platform 不读你本地 php.ini，它只认你明明白白写进去的项。设了 "php": "8.1.25"，不代表 ext-mbstring 或 ext-sodium 就自动“存在”。一旦某个包 require "ext-sodium": "*"，而你没声明，composer install 就会失败。
- ✅ 必须补全常见扩展：
"ext-mbstring": "*"、"ext-openssl": "*"、"ext-json": "*"、"ext-pdo": "*"、"ext-pdo_mysql": "*" - ⚠️ 扩展名严格是
ext-xxx，不是php-xxx或xxx - 版本号填
*可行，但建议填具体值（如"8.1.25"），避免某些包校验逻辑误判
为什么 --ignore-platform-reqs 是饮鸩止渴
遇到 Your requirements could not be resolved 就加 --ignore-platform-reqs？这等于让 Composer 完全跳过所有平台约束，包括 PHP 版本、扩展、甚至其他包的 require 字段。极可能装出语法不兼容、函数不存在、扩展未加载的依赖组合。
立即学习“PHP免费学习笔记（深入）”；
- 正确替代方案：
composer install --platform=php:7.4.33—— 精准伪造 PHP 版本，仅影响本次命令，不污染 lock 或全局状态 -
config.platform对 root package（即本项目自身）的php约束无效；若你在composer.json根级写了"php": "^8.1"，它仍会校验真实环境 - 临时构建可用
--no-platform-check关闭校验，但前提是：你确认代码本身语法兼容实际 PHP 版本
多版本 CI 中真正生效的关键动作
很多人卡在 GitHub Actions 声明了 php-version: 7.4，但 phpunit 仍报 AttributeNotFoundException（PHP 8 特性）。说明实际执行时没切对环境。
- 用
shivammathur/setup-php动作而非系统默认 PHP：它会重置PATH、更新php.ini、并确保composer二进制绑定到当前 PHP 实例 - 务必在
composer install后加php -v && php -m | grep xdebug验证 PHP 版本和扩展是否就位——很多失败源于xdebug在 PHP 8.0+ 默认禁用，而测试框架又依赖它 - 避免在
composer.json的scripts里写死"test": "phpunit"；改成"test": "php $(which phpunit)"，防止缓存了旧路径
最易被忽略的一点：不同 PHP 版本下运行 composer update 生成的 composer.lock 天然不一致——这不是 bug，是预期行为。PHP 7.4 可能锁 monolog/monolog:^2.0，PHP 8.1 可能升到 ^3.0（因 v3 要求 php >= 8.1）。所以跨版本 CI 中，composer install 必须搭配对应版本的 lock 文件，不能共用一份。
