必须在composer.json的config.platform中声明目标PHP及扩展版本(如"php": "8.1.28", "ext-redis": "4.3.0"),该配置仅影响依赖解析阶段,确保拉取兼容包,但不改变运行时行为;require-dev中的ext-*无效,所有运行时依赖须置于require或platform中。

用 platform 声明 PHP 和扩展版本要求
Composer 本身不校验你本地装了什么 PHP 或扩展,它只看 composer.json 里写的约束。如果你在开发机上用 PHP 8.3、ext-redis 5.3.7,但生产环境只有 PHP 8.1 和 ext-redis 4.3.0,composer install 仍可能成功 —— 然后运行时报 Class not found 或 undefined symbol。关键是要提前“骗过” Composer,让它按目标环境解析依赖。
做法是在根 composer.json 的 config 下加 platform 字段:
{
"config": {
"platform": {
"php": "8.1.28",
"ext-redis": "4.3.0",
"ext-mbstring": "8.1.28",
"ext-pdo": "8.1.28"
}
}
}
这样 composer update 就不会拉取需要 ext-redis ^5.0 的包(比如新版 predis/predis 或某些 Laravel Scout 驱动),也不会装要求 PHP 8.2+ 的 spatie/laravel-ray。
-
platform只影响依赖解析,不改变实际运行时行为;它只是告诉 Composer:“就当这些扩展和 PHP 版本已经存在” - PHP 版本必须写成完整小版本(如
"8.1.28"),不能写"^8.1",否则会被忽略 - 扩展名必须是
ext-开头的标准名称(ext-openssl、ext-zip),不是php-openssl或openssl - 如果某扩展在目标环境是通过
--disable-foo编译掉的(比如没开ext-gd),就别写进platform,否则 Composer 会误判兼容性
replace 和 conflict 组合声明“我已自带”
有些系统级能力(比如日志接口、容器契约)本应由框架或基础组件提供,但 Composer 默认还会下载一个空壳包(如 psr/log、psr/container)。这看似无害,实则增加 autoloader 条目、拖慢加载速度,还可能因版本错位引发冲突。
正确做法是用 replace 明确告诉 Composer:“我已经实现了这个虚拟包”,再用 conflict 阻止别人偷偷 require 它:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
{
"replace": {
"psr/log": "3.0.0",
"psr/container": "2.0.2"
},
"conflict": {
"psr/log": "=4.0.0",
"psr/container": "=3.0.0"
}
}
注意:replace 单独用只能避免安装,但无法阻止其他依赖 declare require 同一虚拟包;conflict 是补刀,确保解析阶段就报错,而不是等运行时才发现不兼容。
为什么 require-dev 里的扩展声明无效
很多人把 ext-xml、ext-dom 写进 require-dev,以为能触发检查 —— 实际上完全没用。Composer 对 require-dev 中的扩展约束不做任何验证,它只检查 require 区块。
- 所有影响运行时可用性的扩展,必须放在
require或config.platform里 -
require-dev里的ext-*只是文档作用,CI 脚本或 IDE 不会读它 - 若你只想在 CI 中验证扩展是否启用,得靠 shell 脚本调用
php -m | grep redis,不能依赖 Composer
容易被忽略的共享库版本陷阱
PHP 扩展背后常依赖系统级库(如 hiredis、libssl、zlib)。Composer 管不了这些,但你可以用 platform 间接控制:
-
ext-redis 5.3.7实际绑定了hiredis v1.1.0,而ext-memcached 3.2.0只认hiredis v0.14—— 这类冲突 Composer 解析不出,只能靠你人工对齐platform.ext-redis和platform.ext-memcached版本 - OpenSSL 版本错配会导致
curl_init()失败或 TLS 握手异常,此时要写"ext-openssl": "8.1.28"并确认系统libssl.so.1.1或libssl.so.3存在且路径在LD_LIBRARY_PATH中 - 一旦编译时用了
--with-openssl=/usr/local/ssl,运行时就必须保证该路径下有对应版本的libssl.so,否则Segmentation fault或undefined symbol: SSL_CTX_set_ciphersuites会直接崩掉进程
平台声明不是万能胶,它只解决 Composer 层面的依赖推导。真正的环境一致性,还得靠构建镜像时固定基础系统、锁定扩展编译参数、以及上线前跑一遍 php --ri extname 校验。










