Composer全局镜像配置生效需同时满足三个硬性条件：键名必须为单数repo.packagist、type值必须显式指定为composer、URL须以https://开头且末尾带/，任一缺失均静默回退官方源。
全局配置 composer config -g repo.packagist 一条命令就能生效，但90%的人配不成功——不是网络差，是命令漏了三个硬性条件：键名写错、composer 类型值缺失、URL 缺尾部斜杠。
为什么 composer config -g repo.packagist 没生效
Composer 2.x 遇到配置错误会静默 fallback 到 https://packagist.org，不报错也不提示。常见失效原因：
-
repo.packagist写成repos.packagist（多一个s）或packagist.org - 漏掉中间的
composer——它不是注释，而是必需的type值 - URL 用 HTTP 或末尾没加
/，例如https://mirrors.aliyun.com/composer❌ - Windows 用户手动编辑了
C:\Users\用户名\AppData\Roaming\Composer\config.json，但格式出错或权限不足
验证是否写入成功，只看这一条命令输出：composer config -g repo.packagist。必须返回类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON；空、null、报 Key not found 或只返回原始 URL 字符串（新版行为），都说明失败。
项目级配置比全局更可靠
CI/CD 流水线、宝塔、Docker 容器里常以 www 或 runner 用户运行，根本读不到你本地 root 或当前用户的全局配置。项目级配置写进 composer.json，Git 可追踪、所有人行为一致。
- 进项目根目录，执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不带-g） - 该命令会自动识别已有
repositories结构：如果是对象，就写入"packagist"键；如果是数组，就追加新项，不破坏私有源 - 千万别手动写
"packagist": false，这会导致php、ext-json等基础约束校验失败 - 改完立刻运行：
composer update --lock，确保composer.lock记录的是镜像源地址，而非官方源
换源后仍卡在 “Resolving dependencies”？和镜像无关
镜像只加速元数据拉取和 ZIP 包下载，不参与依赖解析。如果你发现 composer update 卡在 Resolving dependencies 几十秒以上，问题大概率出在：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
composer.json中 PHP 版本约束太宽，比如"php": "^7.4 || ^8.0 || ^8.1"，让 Composer 尝试大量组合 - 存在大量未锁定的
dev-分支依赖，如"monolog/monolog": "dev-main" -
require-dev里塞了太多工具包，尤其是已废弃的fxp/composer-asset-plugin（它绕过 Composer 镜像，直连 Bower/NPM） - 本地
~/.composer/cache损坏，可尝试composer clear-cache后重试
用 composer update -vvv 观察日志里实际请求的域名，能快速区分是镜像没生效，还是真卡在解析逻辑里——后者得调 composer.json，不是换源能解决的。
临时调试用 --repository 最直观
不想动配置、又想确认某次命令是否走镜像？直接加参数最干净：
composer create-project laravel/laravel myapp --repository=https://mirrors.aliyun.com/composer/composer require monolog/monolog --repository=https://mirrors.tuna.tsinghua.edu.cn/composer/ -vvv
-vvv 会打印真实请求 URL，一眼看到是不是发到了 mirrors.aliyun.com；这个参数只对当次命令生效，不影响任何配置文件，适合 CI 脚本或临时排查。
最易被忽略的一点：镜像同步有延迟，新发布的包可能 5–30 分钟后才出现在国内镜像站。如果某个包死活装不上，先查 composer show vendor/package -vvv 看请求路径，再上镜像站网页搜一下，别急着删缓存或重装 Composer。
