Composer镜像源切换：命令行操作详解-composer-PHP中文网

composer config -g repo.packagist 命令失效因三要素缺失：漏 -g、键名误写为 repos.packagist、url 缺末尾 /；正确应为 repo.packagist（单数小写）、含 "type": "composer"、url 以 https://.../ 结尾；验证需输出完整 json 对象。

composer镜像源切换：命令行操作详解

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

不是网络慢，是命令缺了关键三要素：漏 -g、键名写成 repos.packagist、URL 少末尾 / —— 任一出错都静默回退官方源，且完全不报错。

repo.packagist 必须是单数、全小写、无 s；写成 repos.packagist 或 packagist.org 会存进无效字段，composer config -g repo.packagist 查出来为空或 null
composer 是必需的 type 值，不是注释；漏掉它，Composer 2.0+ 直接 fallback 到 packagist.org
URL 必须以 https:// 开头，且末尾带 /；否则请求路径拼成 /composerpackages.json，直接 404 或报 Invalid repository type
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON 对象，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}

Composer 2.2+ 推荐用 repositories.packagist.org 键名

新版 Composer（2.2+）对 repo.packagist 支持不稳定，部分版本会静默忽略；改用 repositories.packagist.org 更稳妥，兼容性更好。

First Principles Decomposer

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

下载

设阿里云源：composer config -g repositories.packagist.org '{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}'
设腾讯云源：composer config -g repositories.packagist.org '{"type": "composer", "url": "https://mirrors.cloud.tencent.com/composer/"}'
验证是否写入：composer config -g repositories.packagist.org，应输出完整 JSON，不是空或报错
注意：JSON 字符串需用单引号包裹（Shell 下），双引号内嵌需转义；Windows PowerShell 用户建议统一用单引号

项目级配置比全局更可靠，但要注意覆盖逻辑

进项目根目录后运行不带 -g 的命令，会修改 composer.json 的 repositories 字段——适合团队协作、CI 部署，行为可 Git 跟踪，但容易误覆盖已有配置。

安全追加方式：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g）
前提：原 "repositories" 是对象（如 {"packagist": {}}），不是数组；若是数组，命令会失败，需先手动转格式
已有私有仓库不会被覆盖，但若 "repositories" 是空对象 {} 或数组 []，该命令仍能 merge；若已是数组且含其他源，必须手动编辑避免冲突
切完立即执行 composer clear-cache，否则旧缓存可能仍触发 packagist.org 请求

临时调试别动配置，用 -r 参数最干净

CI 脚本、帮同事排查、或只试一次 create-project 时，硬改全局或项目配置反而污染环境。用 -r 参数指定源，不写任何配置文件，执行完即失效。

单次命令指定源：composer create-project laravel/laravel myapp -r https://mirrors.aliyun.com/composer/
仅当前项目生效（不写进 composer.json）：composer config repo.packagist composer https://mirrors.ustc.edu.cn/composer/
调试真实请求地址：composer update -vvv --repository=https://mirrors.cloud.tencent.com/composer/，日志第一行会显示实际下载 URL
注意：-r 是短参数，不是 --repository-url；后者在新版中已弃用或不识别

真正卡住的点往往不在镜像地址本身，而在 composer clear-cache 没执行、或 repositories 字段在 composer.json 里被设为数组却没意识到命令无法 merge。