仅靠 composer install 无法保证扩展一致，它只锁包版本，不校验、不安装、不报错缺失扩展；真正起作用的是 config.platform 声明 + composer.lock 生成时机 + 运行时环境三者配合。
仅靠 composer install 无法保证扩展一致——它只锁包版本，不校验、不安装、不报错缺失的扩展。 真正起作用的是 config.platform 声明 + composer.lock 生成时机 + 运行时环境三者配合。漏掉任一环，就会出现“本地能跑、CI 报 ext-gd 缺失”这类问题。
为什么 ext-gd 缺失时 composer install 不报错
Composer 默认只在 composer update 或首次 install（无 lock 文件）时做平台能力校验；一旦 composer.lock 已存在，install 就跳过所有平台检查，直接按锁文件装包。这意味着：
- 如果 lock 文件是在一台有
ext-gd的机器上生成的，那没装 gd 的机器也能成功install，但运行时调用imagecreatefrompng()就会 fatal error -
composer validate不检查扩展，composer diagnose虽然会提示“gd is missing”，但它只是建议，不阻断命令执行 - CI 流程里若只跑
composer install，根本发现不了扩展缺失，直到 PHP 脚本真正执行时才崩
用 config.platform 显式声明扩展，让依赖解析“提前兜底”
在 composer.json 的 config.platform 段写死关键扩展，不是为了“假装有”，而是强制 Composer 在解析阶段就按目标环境选包——哪怕你本地没装，它也会避开那些强依赖 ext-gd 的高版本包（比如某些图像处理库 v3 要求 gd ≥ 8.1，v2 只要 gd 存在即可）。
正确写法示例：
"config": {
"platform": {
"php": "8.1.0",
"ext-gd": "8.1.0",
"ext-mbstring": "8.1.0",
"ext-xml": "8.1.0"
}
}
- 写
"ext-gd": "8.1.0"比写"ext-gd": "1"更稳妥：前者明确要求与 PHP 主版本对齐，避免因扩展 ABI 不兼容导致运行时 segfault - 不要只写
"ext-gd": true或空字符串，Composer 不识别布尔值或空值，会静默忽略 - 这个配置必须提交进 Git，否则新人
clone后运行composer install，仍按本地真实环境解析（可能装进不兼容包）
--ignore-platform-reqs 是临时止痛药，不是解药
它绕过所有平台检查，包括 PHP 版本和扩展，常被误用于“先装下来再说”。但风险极高：
- 加了它，
composer install可能装入带 PHP 8.2 语法（如match表达式）的包，而你本地是 PHP 8.1，运行即ParseError - CI 脚本里若用了
--ignore-platform-reqs，等于主动放弃环境一致性防线 - 真要用，也应限制范围：
composer install --ignore-platform-req=ext-gd比全忽略更安全，至少还校验 PHP 版本 - 它不会修改
composer.json，也不会影响后续命令——下一次composer update依然会报错，除非你再加一遍
生产环境必须做运行时扩展校验
composer.lock 和 platform 解决的是“装什么”，不是“能不能跑”。上线前最后一道关卡，得由 PHP 自己确认：
- 在部署脚本末尾加一行：
php -m | grep -q gd || (echo "ext-gd missing" >&2; exit 1) - 或用现成工具：
composer check-platform-reqs（需 Composer 2.2+），它会读取platform配置并校验当前环境是否满足 - Dockerfile 中别只写
RUN docker-php-ext-install gd，要加验证：&& php -m | grep gd，防止构建中途失败却没暴露 - 本地开发用 Docker 的话，在
docker-compose.yml的healthcheck里加入扩展检测，容器启动后自动验
最易被忽略的一点：团队里有人手动改过 php.ini 关闭了某个扩展，或者用的是不同 SAPI（CLI vs FPM）导致扩展加载不一致——platform 声明再准，也救不了这种运行时割裂。所以，环境描述不能只写在 composer.json 里，还得落到容器镜像或自动化部署脚本中。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
