必须配置国内镜像源，正确命令为composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，三要素缺一不可：repo.packagist（非repos）、type值composer、HTTPS且末尾带/；生效后应输出完整JSON；换源后需清除缓存并重装依赖。
国内直连 packagist.org 基本不可用，不是“慢一点”，而是 TLS 握手卡死、HTTP/2 404、元数据请求超时——必须配镜像，且必须配对。
composer config -g repo.packagist 命令必须写全三要素
90% 的失败源于命令漏写或写错。生效的唯一正确形式是：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
三个关键点缺一不可：
-
repo.packagist（不是repos.packagist，多一个s就完全无效） -
composer是 type 值，不能省略（否则旧版 fallback 官方源，新版直接静默失败） - URL 必须是 HTTPS 且末尾带
/（https://mirrors.aliyun.com/composer会 404；http协议被 Composer 2.0+ 拒绝）
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON，例如：{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}。如果返回空、null 或报错，说明没写进去。
项目级配置比全局更安全，但别覆盖已有 repositories
进项目根目录后执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g），它会往 composer.json 的 repositories 字段里写入 "packagist" 子项。
但注意：这条命令是「全量替换」repositories 对象，不是追加。如果你项目原本已定义私有包源，比如：
"repositories": {
"my-private": {"type": "vcs", "url": "https://git.example.com/pkg"}
}
执行后整个 repositories 会被清空，只剩阿里云镜像——私有包立刻找不到。
正确做法是手动编辑 composer.json，确保结构类似：
"repositories": {
"packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"},
"my-private": {"type": "vcs", "url": "https://git.example.com/pkg"}
},
"packagist.org": false
其中 "packagist.org": false 必须写在根节点（非 repositories 内部），否则 Composer 仍会回源。
临时换源只认 --repository，不认 --repository-url
调试或 CI 脚本中不想改任何配置？用 --repository 参数强制指定一次：
composer update -vvv --repository=https://mirrors.tencent.com/composer/
加上 -vvv 才能看到真实请求 URL，这是唯一确认是否走镜像的方式。常见错误：
- 写成
--repository-url：Composer 不识别，静默忽略，仍走默认源 - 写成
--mirror：不存在该参数，报错退出 - 项目中已有
repositories配置：--repository会完全覆盖整个列表，私有源失效
所以临时换源适合单次验证或隔离环境，不适合混用私有包的项目。
换源后首次 install/update 失败，大概率是缓存和 lock 文件冲突
即使镜像配置正确，首次运行 composer install 仍可能报 hash 不匹配、packages.json 404 或 Resolving dependencies 卡住几十秒。这不是镜像问题，而是本地状态残留：
-
composer.lock记录的是旧源下载的包哈希和版本路径，新镜像返回的元数据结构或签名策略不同，校验必然失败 - Composer 本地缓存（
~/.composer/cache）里还存着旧的packages.json索引，首次重建索引需时间 -
Resolving dependencies卡住 ≠ 下载慢，那是 SAT solver 在本地穷举版本组合，和镜像无关；可删composer.lock后加--with-all-dependencies重试
最稳妥做法：删掉 vendor 和 composer.lock，再跑 composer install -vvv。看到请求域名变成 mirrors.aliyun.com，且无 404，才算真正跑通。
