composer 2.x 镜像配置必须同时满足三个条件才生效：使用 -g 参数、键名为 repo.packagist（单数小写）、type 值为 composer 且 url 以 / 结尾；否则静默回退官方源。
配了镜像但 composer install 还是卡在 “Loading composer repositories”，大概率不是网络问题，而是配置没生效——Composer 2.x 对写法极其敏感，错一个字符就静默 fallback 到官方源。
为什么 composer config -g repo.packagist 总不生效
这条命令必须同时满足三个硬性条件，缺一不可：
-
-g参数不能省：漏掉就只改当前项目composer.json，换目录即失效 - 键名必须是
repo.packagist（单数、全小写、无s）：写成repos.packagist或packagist.org会被忽略 -
composer是必填的type值，不是可选参数：漏掉它，Composer 直接走https://packagist.org - URL 必须是 HTTPS 且以
/结尾：比如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（会拼出/composerpackages.json导致 404）
验证是否成功：运行 composer config -g repo.packagist。输出必须是完整 JSON 对象，例如：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、报错或只返回字符串，都说明失败。
项目级配置怎么安全追加而不破坏私有源
全局配置在 CI、宝塔或多人协作中容易失效（比如命令以 www 用户执行，但 -g 写的是 root 的配置）。项目级更可靠，且可 Git 跟踪：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 进项目根目录，执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不加-g） - 如果原
composer.json中"repositories"是对象（如{"packagist": {}}），命令会自动合并；如果是数组（如[{}]），命令会失败，需先手动转为对象格式 - 已有私有仓库时，千万别直接覆盖
"repositories"字段——用命令追加，它会保留原有内容，只更新packagist子项 - 改完后必须运行：
composer update --lock，否则composer.lock仍记录旧源地址
换源后仍卡在 “Resolving dependencies”？那和镜像无关
镜像只加速元数据拉取和 ZIP 下载，不解决依赖解析慢的问题。如果你发现 composer update 卡在 “Resolving dependencies” 几十秒以上，重点检查：
-
composer.json中 PHP 版本约束太宽，比如"php": "^7.4 || ^8.0 || ^8.1"，会让 Composer 尝试大量组合 - 存在未锁定的 dev 分支依赖，如
"monolog/monolog": "dev-main"，每次都要重新解析整个分支历史 -
require-dev里塞了太多工具包（如phpunit/phpunit+friendsofphp/php-cs-fixer+infection/infection），大幅增加解空间 - 启用了已废弃的
fxp/composer-asset-plugin（常见于老 Yii2 项目），它绕过 Composer 镜像机制，直连 Bower/NPM 源
CI/宝塔环境里全局配置为啥总失效
全局配置文件默认写在 ~/.composer/config.json，但它只对当前用户生效。而宝塔「一键部署」、PHP 管理器、计划任务通常以 www 用户运行，根本读不到 root 或你个人用户的配置。
解决方法很直接：
- 先确认实际执行用户：在宝塔终端或日志里查
whoami或 UID - 再针对性执行配置：比如确认是
www用户，就用sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 或者干脆放弃全局，统一用项目级配置——它不依赖用户上下文，行为确定
最易被忽略的一点：换源之后，vendor/ 和 composer.lock 里的旧记录不会自动刷新。务必执行 composer clear-cache、删掉 vendor 和 composer.lock，再跑一次 composer install，才能真正看到镜像域名出现在日志里。
