Composer的config.platform：一份被误解的“环境模拟”说明书
先澄清一个最常见的误解：Composer 的 config.platform 配置，其核心作用并非“让本地开发环境假装拥有某个扩展”。 恰恰相反，它是用来强制Composer在解析依赖关系时，只考虑目标部署环境（如生产服务器或CI）真实具备的PHP版本和扩展。 这个配置一旦写错或理解偏差，最直接的后果就是：composer install 安装的依赖包组合，在线上环境根本跑不起来。
为什么CI上总报“ext-redis missing”，但本地明明有？
这个问题几乎成了Composer依赖管理的“经典入门题”。根源在于，Composer默认的行为逻辑是：基于你运行Composer命令时的本地PHP环境来解析和选择包。 假设你本地是PHP 8.3并安装了redis扩展，Composer就会认为这个环境是“标准”，并据此选择可能依赖ext-redis的包版本。
然而，CI或生产服务器可能是另一番景象：比如PHP 7.4且没有安装redis扩展。Composer本身不会、也不可能去远程探测目标机器的环境。这时，config.platform 就派上了用场——它让你能明确告诉Composer：“别管我本地有什么，请按照我指定的这个环境来选包。”
配置时，有几个细节必须敲黑板：
- 位置绝对关键：
config.platform必须写在composer.json的config字段之下。写在根级或者混进require里，配置完全无效。 - PHP版本要精确到修订号：比如目标环境是
php -v输出的8.1.27，配置里就必须写"php": "8.1.27"。如果只写"8.1"，Composer会将其解释为^8.1，可能引入要求PHP 8.2的包，埋下兼容性隐患。 - 扩展版本写“*”需谨慎：对于扩展，写
"ext-redis": "*"通常表示“只要存在该扩展就行”。但注意，像symfony/cache这样的包，可能会检查ext-apcu的具体版本是否 ≥ 5.1.12。此时，就必须写死确切的版本号。 - lock文件不会自动更新：修改
platform配置后，已有的composer.lock文件不会自动响应。要让新配置生效，要么删除composer.lock重新运行install，要么在更新时加上--with-all-dependencies参数强制重新计算依赖树。
platform里配置了ext-gd，但线上没装gd扩展，代码为什么还是崩了？
这是另一个理解误区。config.platform 的职责范围仅限于依赖解析阶段。它只负责“选包”，不负责“检测环境”、“安装扩展”或“提供运行时替代方案”。
简单来说，它只是对Composer说：“请假设目标环境长这样，并据此选择合适的包。” 一旦包被安装，代码实际运行时，如果调用了 imagecreate() 这类函数，而系统压根没装gd扩展，PHP照样会抛出致命的Fatal Error。
这里还有几个更隐蔽的坑：
- 虚拟扩展的干扰：有些包（例如
symfony/polyfill-gd）会通过provide声明来“虚拟提供”某个扩展。此时，你在platform中配置的ext-gd可能会被绕过，因为Composer认为该扩展已被“提供”。但务必注意，这类polyfill通常只覆盖了部分函数，可能无法提供完整的资源类型（如GDImage对象）。 - 安全的架构设计：真正治本的方法是，将强依赖特定扩展的功能（如Redis缓存）进行隔离，设计成可选的驱动。或者，直接准备一个无需扩展的fallback方案（比如降级到文件缓存）。
- 如何确认生效配置：使用
composer show -p命令，可以清晰地列出当前实际生效的platform配置列表，这有助于排查配置是否被命令行参数或环境变量意外覆盖。
哪些platform条目是Composer真正识别的？
Composer官方明确识别和支持的“平台包”只有以下四类，除此之外的条目写了也无效：
php：必须项。指定PHP的主版本、次版本和修订号（例如"8.1.27"）。ext-xxx：扩展包，如ext-pdo,ext-json。版本号可以写*或具体值。lib-xxx：有限支持的库，如lib-pcre。但绝大多数第三方包并不会去检查这类依赖。api-xxx：极少使用的API版本标识，如api-zend，基本可以忽略。
另外，ext-xxx 的名字必须和 php -m 命令输出的扩展名完全一致，注意大小写敏感（例如，ext-intl 不等于 ext-INTL）。
说到底，config.platform 不是一种“兜底”或“模拟”方案，它是一份部署环境的契约声明。配置写得越精确、越贴近真实服务器，生成的 composer.lock 文件就越可靠。反之，如果配置模糊或过于乐观，直到上线前的最后一刻才暴露出环境不兼容的问题，那将是代价最高昂的调试成本。
