推荐使用 composer config -g repo.packagist 配置全局镜像源，因其自动处理JSON格式、路径权限及字段校验，确保URL正确包裹且末尾带/；手动编辑~/.composer/config.json易因语法或权限问题导致静默失效。
全局镜像源配置写在 ~/.composer/config.json 里，但别手改——用 composer config -g 命令写入才真正生效，且能绕过 JSON 格式、路径、权限等常见翻车点。
为什么 composer config -g repo.packagist 是唯一推荐的写法
直接编辑 ~/.composer/config.json 容易出错：JSON 缺少逗号、引号不闭合、字段名拼错（比如写成 repos.packagist 或 mirror）、路径权限不对（尤其在 Docker 或宝塔中），都会导致配置静默失效。
composer config -g 自动处理所有细节，只改目标字段，不碰其他配置。它识别 repo.packagist 这个固定 key（1.x 和 2.x 都认），并确保 URL 被正确包裹为 Composer 可解析的仓库定义。
- 必须写
repo.packagist，不是repositories或packagist - URL 末尾必须带
/，例如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌ - 命令中
composer是 type 字段值，不能省略，否则会被当成普通 URL 处理 - Windows 用户执行后需重启终端，否则环境变量或配置缓存可能未刷新
项目级配置优先级更高，怎么检查它有没有盖掉全局设置
进项目目录后运行 composer config repo.packagist：
- 如果输出一个 URL，说明项目自己写了
repositories，全局配置被跳过 - 如果提示
Key "repo.packagist" does not exist，才轮到读全局
项目级配置通常藏在 composer.json 的 repositories 字段里。哪怕只有空对象 "repositories": {}，也会触发“禁用默认源”逻辑，全局镜像完全不生效。
验证实际行为更简单：加 -vvv 执行一次 composer install，搜日志里的 GET https://... 请求地址——看到的是 mirrors.aliyun.com 还是 packagist.org，一眼就清楚。
Docker、CI/CD、宝塔面板里镜像不生效的根因
这些环境常忽略用户上下文：
- Docker 容器默认没有
~/.composer目录，composer config -g写进去也随容器销毁而消失；必须在Dockerfile的RUN阶段显式执行该命令 - 宝塔后台「PHP 管理器」或「计划任务」往往以
www用户身份运行，但你用root执行了composer config -g，结果配置写进了/root/.composer/config.json，www用户根本读不到 - GitHub Actions 等平台若只缓存
vendor/，不缓存~/.composer，每次构建都重走默认源；建议缓存整个~/.composer目录
CI 场景下最稳的做法，是在 composer.json 里声明 repositories，虽然不算“全局”，但能确保构建行为可复现、不依赖宿主环境。
阿里云、华为云、腾讯云镜像 URL 差异和兼容性要点
不同镜像服务的路径结构不同，不能简单替换域名：
- 阿里云：
https://mirrors.aliyun.com/composer/（最稳，同步快，CDN 全） - 腾讯云：
https://mirrors.cloud.tencent.com/composer/（注意是cloud.tencent.com，不是tencent.com） - 华为云：
https://mirrors.huaweicloud.com/repository/php/composer/（路径含/repository/php/，漏掉就 404）
旧镜像 https://packagist.phpcomposer.com 已停用，访问返回 404；https://pkg.phpcomposer.com 同样不可用。别踩这个坑。
某些老旧 PHP 版本（如 7.0 以下）不支持 SNI，HTTPS 镜像会握手失败；临时调试可用 HTTP（仅限本地），但生产环境必须用 HTTPS 镜像。
