PHP包管理指南：Composer国内镜像配置详解-composer-PHP中文网

composer镜像配置失败主因是命令写错：键名必须为repo.packagist（单数小写）、type值必填composer、url末尾必须带/，缺一即静默回退至packagist.org。

php包管理指南：composer国内镜像配置详解

Composer 默认直连 packagist.org，在国内环境下大概率卡在 Loading composer repositories 或 Downloading，不是你网络差，是源没配对——配错一个字符就等于没配。

几乎全是这三个硬伤导致的静默失效：

repo.packagist 键名写成 repos.packagist（多一个 s）或 packagist.org（少 repo. 前缀）
漏掉中间的 composer type 值，比如写成 composer config -g repo.packagist https://mirrors.aliyun.com/composer/
URL 末尾缺斜杠 /，例如 https://mirrors.aliyun.com/composer ❌，必须是 https://mirrors.aliyun.com/composer/ ✅

验证是否真写进去了，只看这一条命令输出：composer config -g repo.packagist。输出为空、null、报 Key does not exist，或者只返回一串 URL 字符串（新版 Composer 行为），都说明配置失败。别信“命令没报错就成功了”。

团队项目常带私有包源，手动改 composer.json 极易格式出错或误删已有 repositories。安全做法是让 Composer 自动合并：

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

进项目根目录（含 composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不加 -g）
如果原 composer.json 是 "repositories": {}，它会自动转成数组并追加 packagist 条目
如果原 repositories 已是数组，它会在末尾插入新对象，不碰已有私有源
千万别手动写 "packagist": false，这会让基础扩展（如 ext-json）校验失败

改完立刻运行 composer update --lock，确保 composer.lock 记录的是新镜像的元数据哈希，否则后续 install 仍可能 fallback 到官方源。

全局配置写在 ~/.composer/config.json，但只对当前用户生效。宝塔默认用 www 用户跑 PHP，GitHub Actions 用 runner 用户，它们根本读不到你本地 root 或 admin 的配置。

查清实际执行用户：whoami 或看日志 UID
给对应用户单独配：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
Docker 构建时，-g 配置不持久，必须把镜像写进 composer.json 才能每次生效

换源后首次 composer install 报 hash does not match 或 package is not installed？直接删掉 vendor/ 和 composer.lock，再重装——旧 lock 文件记录的是官方源的哈希，和镜像元数据不兼容。

镜像只加速下载和元数据拉取，不解决 Resolving dependencies 卡顿；那个阶段慢，得看 PHP 版本、config.platform.php 设置、以及 lock 文件是否老旧。