Composer镜像配置必须同时满足三个硬性条件才生效：键名严格为单数repo.packagist、第二参数显式写composer（type值）、URL须HTTPS且末尾带/，任一缺失即静默回退官方源，验证需执行composer config -g repo.packagist并输出完整JSON对象。
配错就静默走官方源，根本不会报错——这是 Composer 镜像配置最危险的地方。
composer config -g repo.packagist 命令必须写对三个硬性参数
这条命令不是“大概能用就行”，漏掉任意一个要素，Composer 2.x（含当前主流 2.9.6）都会直接 fallback 到 https://packagist.org，且不提示、不报错、日志里也看不出异常。
-
-g不可省：缺了就只改当前目录的composer.json，换项目或新开终端立即失效 - 键名必须是
repo.packagist（单数、小写、无 s）：写成repos.packagist、packagist.org或Repo.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，或者只输出一串 URL 字符串（新版行为），说明配置根本没写进去。
- Windows 用户改完需重启终端，否则缓存和环境变量不刷新
- CI/CD 流水线（如 GitHub Actions）或宝塔后台常用
www-data或runner用户执行命令，-g配的是当前登录用户，权限不一致等于白配 - 某些项目
composer.json里写了"packagist.org": false，会直接屏蔽全局镜像，得手动删掉或改成true
项目级配置比全局更可靠，但要注意结构冲突
只要项目根目录的 composer.json 中存在 repositories 字段，全局配置就彻底失效——不是优先级低，是直接跳过，且不提示。
- 推荐进项目目录后运行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g） - 该命令会自动在
composer.json顶层写入"repositories"字段，key 固定为"packagist" - 如果
composer.json中"repositories"是数组形式（[]），命令会失败；需先手动改为对象："repositories": {}再重试 - 已有私有源时，别手写 JSON——容易格式错误；用命令写入更安全，它会合并而非覆盖
换源后仍卡住或报错，该清什么、不该清什么
镜像只影响元数据和 ZIP 包下载路径，不解决依赖解析、PHP 扩展缺失或缓存污染问题。
- 必须执行：
composer clear-cache——旧缓存里存的是官方源 URL 和 hash，不清掉，composer update仍可能校验失败 - 删掉项目下的
vendor/和composer.lock再跑composer install：lock 文件里的 hash 来自旧源，和镜像元数据不匹配会导致安装中断 -
composer update不会重新加载镜像配置，它只基于现有composer.lock解析依赖；要彻底重走镜像流程，必须删 lock 后重装 - 卡在
Resolving dependencies？和镜像无关，典型诱因是"php": "^7.4 || ^8.0"这类宽泛约束，或require-dev里塞了太多未锁定版本的工具链
最容易被忽略的是：项目级 repositories 字段的存在本身就会让全局配置完全失效，而且 Composer 不做任何提醒。你看到的“配好了”，很可能从一开始就没走镜像。
