composer config -g repo.packagist 总不生效是因为键名必须为单数 repo.packagist、type 值必须显式写 composer、url 必须以 https:// 开头且末尾带 /，三者缺一即静默回退至 packagist.org；验证需输出完整 json 如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，空、null 或官方地址均说明未生效。
composer config -g repo.packagist 命令为什么总不生效
它不是“偶尔失效”，而是三个硬性条件缺一即静默 fallback 到 https://packagist.org，且不报错、不提示：
– 键名必须是 repo.packagist（单数，写成 repos.packagist 或 repositories.packagist 都无效）
– 中间的 composer 是必填的 type 值，不是注释，漏掉就等于没配
– URL 必须是 HTTPS 且末尾带 /，例如 https://mirrors.aliyun.com/composer/✅，少斜杠会请求 /composerpackages.json 导致 404
验证是否真写进去了，别只看命令执行完有没有报错：运行 composer config -g repo.packagist。输出必须是完整 JSON 对象，比如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果返回空、null、Key "repo.packagist" does not exist，或者还是 https://packagist.org，说明配置根本没落盘。
项目级配置才是 CI 和团队协作的唯一可靠方式
全局配置写在 ~/.composer/config.json（或 Windows 的 %APPDATA%\Composer\config.json），但 CI 流水线、宝塔后台、Docker 容器通常以 www 或 runner 用户运行，跟你终端里的用户不是同一个——配置根本不可见。
进项目根目录（确保有 composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer（注意：不加 -g，且 URL 末尾**不能带** /）
这条命令会自动往 composer.json 的顶层 repositories 字段写入镜像定义，key 固定为 "packagist"。但前提是：
– 原 "repositories" 是对象结构（{}），不是数组（[]）；如果是数组，命令会直接报错，需先手动改成 "repositories": {}
– 改完必须删掉 vendor/ 和 composer.lock，再跑 composer install，否则旧 lock 文件仍按原地址解析，镜像形同虚设
怎么确认镜像真的在用，而不是“看起来配了”
别信 composer config 的输出，它只告诉你“写了什么”，不等于 Composer “用了什么”。真正生效要看网络请求路径：
运行：composer install -vvv
滚动日志到底部，搜索关键词：
– 出现 mirrors.aliyun.com 或 mirrors.tuna.tsinghua.edu.cn（Composer 2.x 日志常缩写为 mirro...）✅
– 还出现 packagist.org/packages.json 或 packagist.org/p/ ❌
如果日志里仍是官方域名，优先检查：
– composer.json 里 repositories 是否为数组（[]）而非对象（{}）
– 是否存在其他私有源（如 vcs 类型）排在 packagist 前面，导致 Composer 优先从它解析元数据
– composer.lock 是否被保留，它锁死了旧的包地址和 hash，必须清掉重装
换源后卡在 “Resolving dependencies” 怎么办
镜像只加速元数据拉取和 ZIP 包下载，**完全不参与依赖解析过程**。如果你发现 composer update 卡在 Resolving dependencies 几十秒甚至几分钟，问题和镜像无关，大概率出在：
-
composer.json里版本约束太宽，比如"php": "^7.4 || ^8.0"，让 Composer 在大量候选版本中反复试探 -
require-dev里塞了太多未锁定的工具链（如"phpunit/phpunit": "^9"），加剧组合爆炸 - 用了大量
dev-main或分支别名，触发频繁的 Git 元数据解析
这时候该做的是：
– 先跑 composer clear-cache
– 再用 composer install --no-cache -vvv 确认是否还卡在 Loading composer repositories（镜像问题）还是已进入 Resolving dependencies（逻辑问题）
– 如果后者，就得收紧版本号、移除非必要 dev 包，或临时加 --with-dependencies 观察具体哪个包拖慢了解析
