项目初始化前必须配置国内镜像，否则composer init或create-project会卡在“Loading composer repositories”，因默认直连不可达的packagist.org；需严格执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/并验证输出JSON，或改用项目级配置确保生效。
项目初始化前不配镜像，composer init 或 composer create-project 会卡在 “Loading composer repositories” —— 不是网络慢，是它根本连不上 packagist.org。
为什么 composer init 会卡住
这个命令不是只写个 composer.json 就完事。它要实时拉取包索引元数据来支持交互式选包、版本提示、依赖建议等功能。没镜像时，默认直连 packagist.org，国内多数环境 DNS 解析失败或 TLS 握手超时，结果就是卡死不动，且无明确错误提示。
-
composer init过程中任何一次网络请求失败，都会导致中断或回退到本地缓存（可能为空） - 即使你本地有旧缓存，新版 Composer（2.5+）也会强制校验远程仓库可用性，缓存无法绕过
- 别等卡住再查——执行前就该确认镜像已生效
composer config -g repo.packagist 必须写对这三处
这条命令极易静默失效：不报错、不提醒，但后续所有操作仍走默认源。真正生效必须同时满足：
- 键名严格为
repo.packagist（不是repos.packagist，也不是repository.packagist） - 第三参数必须是
composer（这是type值，小写，不可省略） - URL 必须以
https://开头，且末尾带/：https://mirrors.aliyun.com/composer/✅
验证是否写入成功：composer config -g repo.packagist 输出应为完整 JSON，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果返回空、null 或仍是 https://packagist.org，说明没写进去。
项目级配置比全局更可靠
CI、宝塔、Docker 容器里跑命令的用户和你本地不同，-g 配置根本读不到。项目级配置直接写进 composer.json，谁执行都生效：
- 进入项目根目录（确保已有或刚新建的
composer.json），运行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/ - 它会自动在
repositories数组首位插入镜像项，并显式禁用官方源：{"packagist.org": false} - 如果
composer.json已有"repositories": []（空数组），命令会失败；需先手动改为"repositories": {}（空对象）再试 - 改完必须删掉
vendor/和composer.lock，再跑composer install——update会复用旧 lock 文件里的 dist URL，照样连错源
怎么确认镜像真在用
别只信 config -g 输出，它只告诉你“设了什么”，不反映“是否被覆盖”。最准的验证方式是看真实请求：
- 运行：
composer require monolog/monolog -vvv 2>&1 | grep -i "GET\|Downloading" - 观察输出中的域名：要是出现
mirrors.aliyun.com，说明走镜像；只要看到packagist.org或github.com，就还没接管成功 - 特别注意：某些包（如硬编码 GitHub ZIP 下载地址的）会绕过镜像机制，这类问题换源也无效，得单独处理 Token 或 fork 替换
镜像只解决下载环节，不参与依赖解析。如果卡在 Resolving dependencies，问题出在 php 版本约束太宽、require-dev 包冲突或本地 OpenSSL 扩展未启用——这些点容易被当成镜像问题反复折腾。
