Composer config -g repo.packagist 命令失效主因是键名错误（须为单数repo.packagist）、缺type值composer、URL末尾无/，三者任一缺失均静默回退官方源；验证需输出完整JSON对象，空/null/报错即失败。
composer config -g repo.packagist 命令为什么没生效
90% 的配置失败不是网络问题，而是命令写错三个硬性条件：键名必须是 repo.packagist（不是 repos.packagist 或 packagist.org），composer 作为 type 值不能省略，URL 必须是 HTTPS 且末尾带斜杠 /。
漏掉任意一个，Composer 2.x 会静默 fallback 到官方源，不报错也不提示。验证是否成功，只看这一条命令输出：
composer config -g repo.packagist
正确输出应为类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON 对象。如果返回空、null、报错或只有 URL 字符串，说明根本没写进去。
立即学习“PHP免费学习笔记（深入）”；
常见踩坑点：
- Windows 用户误把配置写进自己的
%USERPROFILE%\AppData\Roaming\Composer\config.json，但宝塔或 CI 实际用的是www用户，得用sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 执行前没清缓存，旧的元数据还在本地，导致
composer create-project topthink/think tp-demo仍卡在Downloading - 误用旧写法
composer config -g repositories.packagist，该键名已废弃，必须用repo.packagist
项目级镜像配置怎么避免覆盖私有仓库
全局配置靠不住，尤其团队协作或 CI 场景下，项目级配置才是可提交、可复现的正解。关键不是手动改 composer.json，而是让 Composer 自动合并。
进项目根目录（确保有 composer.json），执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令不加 -g，会自动识别当前 composer.json 中已有 repositories 的结构，并安全追加或更新 packagist 条目，不会删掉你已配好的私有源（比如企业内网包仓库）。
改完后必须做两件事：
- 删掉
vendor/和composer.lock - 运行
composer install（不是update），否则旧 lock 文件仍指向 packagist.org
注意："packagist": false 这种写法会直接禁用基础包校验，导致 php、ext-json 等必需依赖无法解析，绝对不要写。
换源后 still stuck at “Resolving dependencies”？
镜像只加速下载，不解决依赖解析慢的问题。如果你发现 composer update 卡在 Resolving dependencies 几十秒甚至几分钟，基本和镜像无关，而是本地 composer.json 写法或环境导致的。
典型诱因：
-
"php": "^7.4 || ^8.0"这类宽泛版本约束，会让 Composer 尝试大量组合，拖慢解析 - require-dev 里塞了太多未锁定的工具包，比如
"phpunit/phpunit": "^10.0"+"friendsofphp/php-cs-fixer": "dev-main" - 用了已废弃的
fxp/composer-asset-plugin（常见于老版 Yii2 项目），它会额外请求 Bower/NPM 源，而这些源没有国内镜像
临时验证方式：加 -vvv 参数跑一次 composer update -vvv，观察日志里卡在哪一步——如果卡在 Resolving dependencies 阶段，且请求 URL 是 https://packagist.org/...，说明镜像已生效，问题出在解析逻辑本身。
阿里云 / 清华 / 腾讯镜像选哪个
三者同步频率都高（通常 5 分钟内），但稳定性略有差异。阿里云镜像偶尔因 CDN 节点抖动返回 503；清华镜像（https://mirrors.tuna.tsinghua.edu.cn/composer/）在教育网和北方地区延迟更低；腾讯云镜像（https://mirrors.cloud.tencent.com/composer/）在华南和云上环境响应更稳。
实操建议：
- 日常开发首选清华源：命令为
composer config -g repo.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/ - CI 流水线或云服务器部署时，优先试腾讯源，尤其当阿里源出现
Could not fetch时可快速切换 - 换源后务必验证：用
curl -I https://mirrors.tuna.tsinghua.edu.cn/composer/packages.json看是否返回200 OK
最麻烦的不是选哪个镜像，而是换源后忘记删 composer.lock —— 它会死死记住上次解析时用的源地址，哪怕你已经配好新镜像，它照样去 packagist.org 找包。
