Composer config -g repo.packagist 总不生效是因为键名必须为单数repo.packagist、type值必须显式写composer、URL必须HTTPS且末尾带/、命令必须加-g，四者缺一即静默回退官方源。

composer config -g repo.packagist 为什么总不生效

这条命令写错任意一个字符，Composer 就会静默 fallback 到 https://packagist.org，且不报错、不提示。常见失效组合包括：

• repos.packagist（多一个 s）→ 键名非法，配置被忽略
• composer config -g repo.packagist https://mirrors.aliyun.com/composer/（漏掉 composer type 值）→ Composer 2.x 不识别，直接走官方源
• https://mirrors.aliyun.com/composer（末尾缺 /）→ 请求路径变成 /composerpackages.json，返回 404，但 Composer 自动重试并降级回 packagist.org
• 没加 -g → 只改当前项目 composer.json，换目录或换用户就失效
• 用 http:// 协议 → Composer 2.2+ 主动拒绝连接，根本不会发请求

验证是否生效，只看这一行输出：composer config -g repo.packagist。正确结果必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、报错或仍显示 https://packagist.org，说明根本没写进去。

项目级配置比全局更可靠

全局配置依赖当前用户家目录下的 ~/.composer/config.json，但在宝塔、GitHub Actions、Docker 或 CI 中，实际运行用户常为 www、runner 或 root，配置不可见。项目级配置直接写进 composer.json，拉代码即生效，行为可预期。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• 进项目根目录后执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不加 -g）
• 该命令会自动在 composer.json 的 repositories 字段中添加 "packagist" 条目，不会清空已有私有源
• 若原 repositories 是数组格式（[]），命令会报错；需先手动改为对象格式："repositories": {}
• 改完务必删掉 vendor/ 和 composer.lock，再跑 composer install，否则旧 lock 文件里的哈希可能和镜像元数据不匹配

镜像只加速下载，不解决依赖解析卡顿

如果你发现 composer update 卡在 Resolving dependencies 超过 10 秒，这不是镜像问题，而是本地依赖图计算耗时。镜像只加速 Downloading 和 Loading package information 阶段。

• composer install 优先用 composer.lock 恢复，几乎不触发解析，应始终作为部署首选
• 避免无意义的 composer update；如必须更新，加 -vvv 查看卡在哪一步，常见于某个包的 dist 地址返回 404
• 约束太宽（如 "monolog/monolog": "^2.0"）会导致版本回溯过深，大幅拖慢解析；收紧版本范围可显著提速
• 并发下载数默认仅 3，相当于把千兆带宽压成 300KB/s —— 必须显式设置：composer config -g parallel-downloads 8

CI/CD 中镜像失效的隐蔽原因

CI 环境下镜像“配了还是慢”，往往不是命令写错，而是缓存干扰或权限错位。

• CI runner 可能复用旧缓存，或构建镜像时未清理旧 vendor/ 和 composer.lock，导致 Composer 仍从 lock 文件读取原始元数据地址
• 推荐在 CI 脚本开头强制重置：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
• 加 -vvv 运行 composer install，然后 grep mirrors.aliyun.com 确认日志里出现的是镜像域名，而非 packagist.org
• 更稳妥的做法是提交项目级配置到 Git，所有环境自动继承，彻底规避用户权限与缓存问题

真正卡住的从来不是网速，而是配置细节没对齐——键名、type、斜杠、-g，四者缺一不可。一旦写错，Composer 就默默回到海外源，你却还在等它“快一点”。