ThinkPHP项目必须配国内镜像源，否则create-project和install必卡在“Loading composer repositories”；config -g repo.packagist不生效主因是键名错、缺type值或URL末尾无/，三者缺一即静默回退官方源。
ThinkPHP 项目必须配国内镜像源，否则 composer create-project 和 composer install 几乎必然卡死在 “Loading composer repositories” 阶段——这不是网速问题，是 Packagist 官方源在国内不可达导致的硬性失败。
为什么 composer config -g repo.packagist 总是不生效
这条命令写错任意一个细节，Composer 就会静默忽略，继续连 https://packagist.org，且不报错、不提示。
- 键名必须是
repo.packagist（不是repos.packagist、repository或packagist.org） -
composer是强制 type 值，不能省略，也不能写成"type": "composer-type" - URL 必须是 HTTPS，且末尾带
/：例如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌ - 必须加
-g（全局）或确保在项目根目录下执行不带-g的命令；Windows 下若非管理员运行，可能写入失败 - 验证是否真生效，只看这一条：
composer config -g repo.packagist，输出必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
ThinkPHP 初始化必须用 create-project，不是 require
composer require topthink/think 只装源码包，不生成 public/、think 脚本、app/ 目录等骨架文件，直接导致 Class 'think\App' not found 或 Could not open input file: think。
- 正确命令：
composer create-project topthink/think tp6 --prefer-dist（ThinkPHP 6.x） - ThinkPHP 8.x 推荐：
composer create-project topthink/think tp8 - 换源后仍报错？先删掉
vendor/和composer.lock，再重跑create-project——update不会重建骨架 - 不要加
--repository参数初始化 ThinkPHP，它会绕过全局配置但无法保证后续依赖一致
项目级配置比全局更可靠，尤其在协作和部署环境
宝塔、GitHub Actions、Docker 容器里默认以 www 或 runner 用户运行，根本读不到你本地 ~/.composer/config.json。项目级配置写进 composer.json，Git 可追踪、CI 可复现。
立即学习“PHP免费学习笔记（深入）”；
- 进入项目根目录，执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 该命令会向
composer.json写入"repositories"字段；如果已有私有源，建议手动编辑，把阿里云镜像对象放在repositories数组首位 - 务必确认
"packagist.org": true（不是false），否则基础包如psr/log会拉不到 - 改完后必须删
vendor/和composer.lock，再执行composer install，否则旧 lock 文件仍指向官方源地址
最常被忽略的一点：换镜像源 ≠ 换完就立刻生效。缓存、lock 文件、vendor 目录三者中任一残留旧状态，都会让 Composer 继续往 packagist.org 发请求——哪怕你已经反复确认 config -g repo.packagist 输出正确。
