根本原因是Composer默认直连海外packagist.org导致TLS握手慢、首字节延迟高甚至503超时，解决方法是执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/配置全局镜像，并验证输出含阿里云URL。
为什么ThinkPHP项目总卡在Downloading或报“could not find package”
根本不是你网络差，而是Composer默认直连packagist.org——物理距离远、TLS握手慢、DNS解析不稳定，国内访问经常首字节延迟超10秒，甚至直接503。ThinkPHP依赖链深（topthink/framework → topthink/think-orm → topthink/think-view等），一个包卡住，整个composer install就挂。
全局镜像必须用composer config -g repo.packagist命令配
别手动改~/.config/composer/config.json，容易格式错或路径错。执行这条命令才真正生效：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
注意三个硬性要求：
-
repo.packagist键名不能多s、少repo.，也不能写成repositories - 中间的
composer是type值，不可省略 - URL末尾必须带
/，写成https://mirrors.aliyun.com/composer会静默失败
验证是否成功：运行composer config -g repo.packagist，输出必须是完整JSON对象或至少是字符串"https://mirrors.aliyun.com/composer/"；如果返回空、null或报Key不存在，说明没写进去，立刻重试。
立即学习“PHP免费学习笔记（深入）”；
CI/CD和团队协作时，光配全局镜像不够
GitHub Actions、GitLab CI、宝塔面板里的www用户，都读不到你本地用户的全局配置。必须把镜像源写进项目本身：
进入项目根目录（含composer.json），执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令会自动在composer.json里追加repositories字段，不破坏原有结构。改完后务必删掉vendor/和composer.lock，再跑composer install（不是update）。
手动编辑composer.json的风险点：
- 别写
"packagist": false——这会彻底关掉基础包源，topthink/framework都拉不到 -
repositories必须是数组，且阿里云源要放在首位 - 改完不删
composer.lock，install仍可能走旧缓存
ThinkPHP项目里哪些Composer操作最易踩坑
不是所有composer命令都适合TP项目：
-
composer update裸跑等于自毁：它会让topthink/framework升到v8而topthink/think-orm还卡在v2.x，直接报Class not found: think\Model -
composer require topthink/think-captcha不带版本号，可能装v4（适配TP7/8），但你的TP6.3只认v3——应写成composer require topthink/think-captcha:^3.0 -
composer install --no-dev --optimize-autoloader才是上线标准命令；--no-scripts可临时跳过post-install脚本（如清runtime），但后续得补composer run-script post-root-package-install -
vendor/绝不能提交到Git，也绝不能从本地直接rsync到服务器——PHP扩展差异会导致autoload失效
最常被忽略的一点：php think命令本质是vendor/bin/think的符号链接，一旦composer install中途失败或权限异常，这个文件就损坏，错误却只显示Class 'think\App' not found，根本不会提示“bin文件缺失”。
