全局镜像配置仅composer config -g repo.packagist命令有效，必须带-g、键名为repo.packagist、值为含"type": "composer"和以https://开头且结尾带/的URL的JSON对象；项目级需在repositories数组首项显式设{"packagist.org": false}，否则全局配置被跳过。
全局镜像配置只有一条命令真正有效，项目级配置必须显式禁用 packagist.org 才能生效；其他写法大概率静默失败，不是网络慢，是根本没走镜像。
composer config -g repo.packagist 命令为什么总不生效
这条命令看似简单，但漏掉任意一个要素就会静默 fallback 到 packagist.org：不报错、不提示、日志里照旧出现 Downloading https://packagist.org/packages.json。
-
-g不可省：缺了就只改当前目录的composer.json，换项目或新开终端立即失效 - 键名必须是
repo.packagist（单数，不是repos.packagist或repositories.packagist.org） - 中间的
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 not found，或者只有 URL 字符串，说明配置根本没落盘。
项目级 repositories 配置为何完全屏蔽全局镜像
只要项目根目录存在 composer.json 且含 "repositories" 字段，全局 repo.packagist 就被彻底跳过——这是 Composer 的设计逻辑，不是 bug。
- 检查是否被覆盖：进项目后运行
composer config repo.packagist（不带-g），有输出说明项目级生效了 - 正确结构必须是数组，且顺序不能颠倒：
第一项必须是{"packagist.org": false}（显式关闭官方源）
第二项才是镜像源：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 常见错误：
"repositories": {"type": "composer", "url": "..."}（对象格式，非数组）、漏掉"packagist.org": false、把false放在第二位
想保留私有仓库又加镜像？别手写 JSON，用命令安全合并：composer config repo.packagist composer https://mirrors.aliyun.com/composer/。但如果 "repositories" 是数组格式，该命令会失败，需先手动改为对象再执行。
换源后仍卡在 Loading composer repositories 的真实原因
不是镜像地址不可用，而是 Composer 优先读缓存和旧 lock 文件，根本不发新请求。
- 必须清缓存：
composer clear-cache（推荐）或手动删~/.composer/cache/repo/https---mirrors-aliyun-com-composer/ - 删掉项目下的
vendor/和composer.lock，再跑composer install -vvv - 看日志中是否出现
Reading packages.json from cache at /https---mirrors-aliyun-com-composer/或Downloading https://mirrors.aliyun.com/composer/packages.json -
composer update不会重新加载镜像配置，它只基于现有composer.lock解析依赖；要重走镜像流程，必须删 lock 后重装
Windows 用户改完需重开终端，否则环境变量和配置缓存不会刷新；CI 环境中若用 sudo composer config -g，很可能写进了 root 配置，但构建实际跑在 runner 或 www-data 用户下，得配对应用户的配置文件。
手动编辑 config.json 比命令行更稳的三个理由
命令行容易因拼写、大小写、参数遗漏导致静默失败；直接改文件能一眼确认关键点是否到位。
- 路径必须是
"repositories"数组（不是"repo.packagist"对象），内容为：[{"packagist.org": false}, {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}] - 确保
"packagist.org": false在第一位，否则仍可能回源请求元数据 - 保存时用 VS Code 或 Notepad++，选 UTF-8 无 BOM 编码，避免中文引号、多余逗号、BOM 头等 JSON 格式错误
改完仍要执行 composer clear-cache，否则缓存里的旧 packages.json 还指向 packagist.org。验证是否真走镜像，唯一可靠方式是 composer install -vvv 并搜索日志中的 GET 行，确认域名是你配的镜像地址——快慢不是判断依据，域名才是。
