必须先执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/并清缓存，否则直连packagist.org易因网络延迟报错；验证需输出完整JSON对象，漏斜杠、拼写错误或键名不匹配均导致静默失效。
直接用 composer create-project topthink/think 就能装最新版 ThinkPHP，但八成会卡在 Downloading 或报 could not find package——不是你网络差，是 Composer 默认还在直连 packagist.org，国内访问延迟高、TLS 握手慢、甚至 503 超时。
为什么 composer create-project topthink/think 总失败？
ThinkPHP 6+ 已弃用 topthink/think 作为可 require 的包名，它现在是一个项目骨架（skeleton），只能用 create-project 初始化。而失败根源几乎全是镜像问题：
-
composer config -g repo.packagist输出仍是https://packagist.org，说明没配镜像或配置静默失效 - URL 少了末尾斜杠（如写成
https://mirrors.aliyun.com/composer），导致路径拼接出错，返回 404 - 键名写错成
repos.packagist或repo.packagist.composer，Composer 不识别，不报错但不生效 - CI/CD 环境（如 GitHub Actions、宝塔）里执行用户跟本地不同，全局配置根本读不到
composer config -g repo.packagist 必须写对三要素
这条命令不是“试试看”，漏一个就白配。必须同时满足：
- 键名严格为
repo.packagist（不能多s，不能少repo.） - 中间的
composer是 type 值，不可省略（新版 Composer 会 fallback 到官方源） - URL 必须 HTTPS + 末尾带斜杠：
https://mirrors.aliyun.com/composer/✅
验证是否写入成功：运行 composer config -g repo.packagist，输出应为完整 JSON 对象，例如：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果为空、null 或报 Key 不存在，立刻重试，别往下走。
立即学习“PHP免费学习笔记（深入）”；
项目级镜像配置：CI 和团队协作绕不开这步
全局配置在 CI 流水线里基本无效——GitHub Actions 用 runner 用户，宝塔用 www-data，它们都读不到你本地 ~/.composer/config.json。必须把镜像写进项目本身：
- 进入项目根目录（含
composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 这条命令会自动在
composer.json的repositories字段追加，不破坏已有结构 - 改完必须删掉
vendor/和composer.lock，再跑composer install（不是update） - 千万别手动加
"packagist": false，否则基础包全拉不到；要确保"packagist": true或干脆不写这一项
临时验证镜像是否生效：加 --repository 参数
怀疑镜像没起作用？不用反复改配置，直接命令行指定：
- 测试安装：
composer create-project topthink/think tp-demo --repository=https://mirrors.tuna.tsinghua.edu.cn/composer/ - 测试引入扩展：
composer require topthink/think-orm -vvv 2>&1 | grep "Downloading"，看真实请求域名是不是镜像站 - 这个方式不改任何配置文件，执行完即失效，适合快速定位是镜像问题还是包本身问题
真正容易被忽略的不是“怎么配”，而是配完不验证、不清理缓存、不删 composer.lock。尤其多人协作时，有人提交了没删 lock 文件的镜像配置，别人拉下来照样从海外源下载——问题不在你，而在那个没清干净的 composer.lock。
