Composer镜像配置生效需同时满足：键名repo.packagist（单数）、type参数必填composer、URL以/结尾；还需清除PHP禁用函数putenv/proc_open/pcntl_signal并重载配置，否则镜像无效。
宝塔面板里没有“一键更换 Composer 镜像”的按钮，所谓“一键”实际是 3 条命令+1 次 PHP 设置调整，缺一不可。
composer config -g repo.packagist 命令总不生效？
常见现象：执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 后，composer config -g repo.packagist 返回空或 null，composer install 依然卡在 Loading composer repositories。
- 最常踩的坑是键名写错——必须是
repo.packagist（单数repo），写成repos.packagist或packagist.org都会静默失败 - type 参数不能省：
composer是必需值，不是注释，漏掉就 fallback 到官方源 - URL 必须以
https://开头且末尾带/，比如https://mirrors.aliyun.com/composer/，少斜杠会拼出/composerpackages.json导致 404 - 验证是否真生效，别只看命令没报错：运行
composer config -g repo.packagist，正确输出应为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
PHP 禁用函数不清理，镜像再快也启动不了
即使镜像 URL 配对了，composer --version 或 composer install 仍报 Call to undefined function putenv()、proc_open() is not available，说明宝塔 PHP 设置里还锁着关键函数。
- 进宝塔【网站】→【PHP 管理】→ 选中你项目实际用的版本（比如 82，不是“默认”或“当前”）→【禁用函数】
- 手动删除这三项（不是取消勾选，是整行删掉）：
putenv、proc_open、pcntl_signal - 删完必须点【重载配置】或重启该 PHP 版本服务，否则修改不加载
- 验证：在终端执行
php -r "echo putenv('TEST=1');"和php -r "var_dump(proc_open('echo 1', [], $pipes));"，都不报错才算通过
为什么全局镜像对某些站点无效？
现象：全局配置已确认生效，但某个站点执行 composer install 仍走官方源，甚至报 hash does not match。
立即学习“PHP免费学习笔记（深入）”；
- 检查该项目
composer.json是否显式禁用了 packagist："packagist.org": false，若有，需同步改为"packagist.org": true或删掉该行 - 如果
repositories字段是数组格式（如"repositories": []），composer config repo.packagist ...会直接报错；必须先手动改成对象格式："repositories": {} - 部分老项目含私有源配置，若
repositories是对象但不含packagist子项，命令能写入，但首次install可能因composer.lockhash 不匹配失败——此时需删掉vendor/和composer.lock重来
真正容易被忽略的是：镜像只是加速下载，但 Composer 能否跑起来，取决于 PHP CLI 是否可用、函数是否放开、软链接是否建对。三者任一缺失，“换镜像”就只是给一个瘫痪的系统换了个更漂亮的仪表盘。
