必须同时满足六项条件才生效：①结构正确；②字段名严格为repo.packagist；③URL用HTTPS且全局配置末尾带/、项目级不带/；④显式声明"packagist.org": false；⑤清理composer.lock和vendor；⑥执行clear-cache；缺一即静默回退官方源。
直接改 composer.json 或执行 composer config 命令就能生效？不能。必须同时满足结构、字段名、协议、路径结尾、禁用兜底源、清理旧文件这六项，缺一不可，否则 Composer 会静默回退到 https://packagist.org，你看到的“卡住”“404”“Class not found”全是它在假装努力。
composer config -g repo.packagist 命令为什么总不生效
不是镜像地址挂了，是你命令漏了关键要素，而 Composer 不报错也不提示，只默默 fallback。
-
-g必须带——不加就是项目级配置，换目录就失效 - 键名必须是
repo.packagist（单数、小写、无 s），写成repos.packagist或packagist.org都存进无效字段 - 中间的
composer是type值，不是注释，漏掉整个配置被忽略 -
url必须是 HTTPS 且末尾带/：例如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（会拼出/packages.json导致 404）
验证是否真写进去了：composer config -g repo.packagist 输出必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。返回 null、空、或只有一行 URL 字符串，说明失败。
项目级镜像必须写进 composer.json 的 repositories 对象
全局配置在 CI、宝塔、Docker 里大概率读不到——因为运行用户不是你当前登录的用户。项目级配置随代码走，行为可预期，但写法极容易错。
-
"repositories"必须是顶层字段，不能嵌套在config或require里 - 必须用对象
{}，不能用数组[]；如果原先是数组，composer config repo.packagist命令会报错，需先手动改成"repositories": {} -
"packagist"是固定 key，type必须为"composer"，url末尾不能带/（注意：和全局配置相反！项目级url末尾不加/） - 必须同级声明
"packagist.org": false，否则 Composer 仍会把官方源当兜底，部分包走镜像、部分走国外，甚至触发签名验证失败
正确结构示例：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
"repositories": {
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer"
},
"packagist.org": false
}
改完配置后 vendor 和 composer.lock 为什么必须删掉
composer.lock 里记录的是每个包的 dist.url，它指向原始下载地址（比如 https://api.github.com/ 或 https://packagist.org/）。哪怕镜像已配好，composer install 仍会优先尝试 lock 文件里的旧 URL —— 导致超时、404 或 hash 不匹配。
- 不删
vendor和composer.lock，composer install就是在用旧锁文件“假装重装” - 必须执行
rm -rf vendor composer.lock，再跑composer install（不是update） - CI 环境中还要加
composer clear-cache，避免本地元数据缓存干扰
验证是否真走镜像：运行 composer install -vvv 2>&1 | grep "Fetching"，确认输出里是 https://mirrors.aliyun.com/composer/p2/ 这类地址，而不是 https://repo.packagist.org。
临时换源只对当前命令有效，别指望它改配置
想快速验证某个镜像是否可用，或绕过当前配置问题，可以用 --repository 参数：
- 例如：
composer create-project laravel/laravel myapp --repository=https://mirrors.aliyun.com/composer/ - 这个参数只影响当前命令，不修改任何配置文件，也不写入
composer.json - 旧版 Composer 可能不支持该参数，报
Unknown option: repository，此时只能换用项目级或全局配置 - 新项目初始化时若漏加该参数，
create-project会直连packagist.org，绕过全局镜像
最常被忽略的其实是 "packagist.org": false 这一行——它不在文档显眼位置，但没它，镜像只是“备选”，不是“唯一”。很多团队上线前还在用国外源拉包，就是因为这一行被手误删了，或者写成了 "packagist.org": true。
