换镜像无法解决ext-xxx缺失问题，因镜像仅加速下载不干预扩展校验；根本原因是运行环境未加载扩展且config.platform未正确声明ext-xxx格式的扩展版本。
中文镜像本身不解决扩展版本号对齐问题——它只加速包下载，不干预 ext-gd、ext-mbstring 等扩展的声明、校验或安装逻辑。真正起作用的是 config.platform 配置 + 显式扩展声明 + 严格依赖解析流程。
为什么换阿里云/腾讯云镜像后 still 报 ext-xxx 缺失？
因为镜像只代理 Packagist 元数据和 ZIP 包分发，不改变 Composer 的平台能力校验行为。报 ext-gd 缺失，说明：
- 当前运行
composer install的机器上没加载该扩展（php -m | grep gd为空） - 且
composer.json中未在config.platform下声明"ext-gd": "8.1.0" - 且当前处于首次安装或
composer.lock不存在时——此时 Composer 才会检查扩展是否存在
换镜像后仍失败，本质是环境缺失 + 配置缺位，不是网络问题。
config.platform 必须写全扩展名，ext-前缀不能省
config.platform 里声明扩展，必须用 ext-xxx 格式，否则 Composer 完全忽略。常见错误写法："gd": "*"、"php-gd": "1"、"ext.gd": "8.1.0" —— 全部无效。
立即学习“PHP免费学习笔记（深入）”；
正确写法示例（放在 composer.json 的 config 字段内）：
"config": {
"platform": {
"php": "8.1.25",
"ext-gd": "8.1.25",
"ext-mbstring": "8.1.25",
"ext-openssl": "8.1.25",
"ext-pdo": "8.1.25",
"ext-pdo_mysql": "8.1.25"
}
}
注意：
- 版本号建议填具体值（如
"8.1.25"），而非"*"或"^8.1"，避免 ABI 不兼容 - 所有项目依赖的扩展都得列出来，漏一个，
composer update就可能选错包 - 改完必须执行
composer update --lock，否则composer.lock仍按旧平台信息锁定
CI/CD 里光配 platform 还不够，PHP 环境得真装扩展
config.platform 只骗过依赖解析，不帮你装扩展。CI 脚本里如果只写 composer install，而没提前运行 docker-php-ext-install gd mbstring 或对应系统命令，运行时调用 imagecreatefrompng() 依然会 fatal error。
典型 CI 错误流程：
- 配置了
"ext-gd": "8.1.25"→ Composer 选了兼容包 →composer install成功 - 但容器没执行
apt-get install php8.1-gd或docker-php-ext-install gd→php -m不输出gd - PHP 脚本一调用 GD 函数就崩溃
所以 CI 步骤必须包含：
- 确认 PHP 版本（
php -v） - 安装扩展（如 Debian 系：
apt-get install -y php8.1-gd php8.1-mbstring） - 验证加载（
php -m | grep -E '^(gd|mbstring)$'） - 再跑
composer install
--ignore-platform-reqs 是危险开关，别当默认选项
加 --ignore-platform-reqs 后 composer install 是能过，但后果严重：
- 可能装入含 PHP 8.2
match表达式的包，而你本地是 PHP 8.1 → 运行时报ParseError - 可能装入要求
ext-igbinary >= 3.2的包，但你本地只有igbinary 2.0→ 运行时函数不存在 - CI 流水线用了它，等于主动放弃环境一致性防线
真要用，也应最小化范围：
-
composer install --ignore-platform-req=ext（跳过所有扩展检查，但保留 PHP 版本校验） -
composer install --ignore-platform-req=php（仅跳过 PHP 版本，慎用） - 绝不要在 CI 脚本里无条件加
--ignore-platform-reqs
最常被忽略的一点：即使 config.platform 写得再全，只要没在 CI 或本地真实安装对应扩展，php -v 和 php -m 的输出就不匹配，运行时崩是必然的。
