Composer镜像本质是换源而非加速插件，必须显式配置repo.packagist指向国内镜像URL（如https://mirrors.aliyun.com/composer/），且URL末尾必须带/、类型为composer、键名不可拼错，否则静默回退官方源。
Composer镜像不是“加速插件”，而是换源
Composer 本身不自带国内加速能力，它默认只连 packagist.org——这是 PHP 包的原始元数据中心，物理位置在海外。国内直连常出现卡在 Loading composer repositories with package information、超时、could not find package 或 TLS 握手失败，不是你网络差，是路由和防火墙导致的连接不可靠。
所谓“镜像”，就是把 packagist.org 的完整元数据（包名、版本、依赖树、下载链接）实时同步到国内服务器，比如阿里云 https://mirrors.aliyun.com/composer/、腾讯云 https://mirrors.cloud.tencent.com/composer/。它们不是代理，也不是 CDN 缓存，而是独立、全量、延迟 ≤15 分钟的副本源。
关键点在于：Composer 不会自动识别“更快的地址”，必须显式告诉它“以后别找官方，改去这个 URL”。否则它永远优先尝试 packagist.org，失败后才 fallback（且 fallback 行为在 Composer 2.9.6 中已收紧，经常静默失败）。
全局配置命令为什么总不生效？三要素缺一不可
执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 是最快方式，但极易写错。漏掉任意一项，配置就白写，且不报错——查 composer config -g repo.packagist 时可能返回空、null 或旧值。
立即学习“PHP免费学习笔记（深入）”；
-
repo.packagist是唯一合法键名：写成repos.packagist（多 s）、mirror、Repo.Packagist（大小写混用）都会被忽略 -
composer是强制type值：不能省略，也不能写成vcs、package或空字符串 - URL 必须以
/结尾：比如https://mirrors.aliyun.com/composer/✅，少斜杠会拼出/composerpackages.json导致 404，或 fallback 到官方源
验证是否写对：运行 composer config -g repo.packagist，输出必须是完整 JSON 对象，形如 {"type":"composer","url":"https://mirrors.aliyun.com/composer/"}。
项目级配置为何删了 vendor 还不行？顺序和结构决定成败
项目级配置写进 composer.json 后仍走官方源，大概率是结构错误。Composer 要求极严，错一个逗号、少一个中括号、位置不对，整个 repositories 就被忽略。
- 必须放在项目根目录的
composer.json里，写进composer.lock或全局配置文件无效 -
repositories必须是数组（[]），不能是对象（{}） - 镜像对象必须是数组第一个元素，且含
"type": "composer"和完整 URL - 必须显式禁用官方源：
{"packagist.org": false}是独立对象，要和镜像对象并列，不能嵌套、不能合并
正确结构示例：
{
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{
"packagist.org": false
}
]
}
改完必须删掉 vendor/ 和 composer.lock，再执行 composer install（不是 update），否则旧 lock 文件仍指向官方源。
为什么有时临时切镜像反而最可靠？
当全局或项目配置疑似失效、CI 环境权限受限、或需要快速验证某镜像是否可用时，--repository 参数是最干净的方式。它不修改任何配置文件，命令执行完即失效，适合调试。
例如：
composer install --repository=https://mirrors.tuna.tsinghua.edu.cn/composer/
注意：该参数只对当前命令生效，不会影响后续操作；它优先级高于全局和项目配置，但不写入任何文件，也无需清理缓存或 lock 文件。
真正容易被忽略的是：Composer 2.9.6 默认禁用 packagist.org fallback，一旦镜像 URL 拼错或服务异常，它不会“退而求其次”，而是直接报错或卡住——所以验证 URL 是否可访问、是否带结尾斜杠，比调参数更重要。
