直接运行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 即可全自动完成全局镜像配置，该命令自动写入正确路径的 config.json、校验字段合法性、确保 url 末尾带斜杠且 type 值为 composer，兼容 composer 2.x/3.x，无需手动编辑、不依赖环境变量、不用重启终端。
直接运行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 就能完成自动配置，不需要改文件、不依赖环境变量、也不用重启终端——这是 Composer 2.x / 3.x 下唯一推荐的全自动方式。
为什么必须用 composer config -g 而不是手动编辑 config.json
手动写 JSON 容易出错：字段名拼错（比如写成 repos.packagist 或 packagist.org）、少逗号、URL 缺末尾斜杠、type 值漏掉，都会导致静默失效。而 composer config -g 自动处理嵌套结构、校验字段合法性、确保路径正确（Linux/macOS 写入 ~/.composer/config.json，Windows 写入 %APPDATA%\Composer\config.json）。
-
repo.packagist是固定键名，大小写和点号都不能错 - URL 必须以
https://开头，且结尾必须带/，https://mirrors.aliyun.com/composer会 404 - 别加
/packages.json或/dist后缀，镜像服务已做路由代理 - Windows 用户若提示
Permission denied，大概率是 OneDrive 或杀毒软件锁了config.json，临时退出再试
为什么配完还是走 packagist.org
不是命令没生效，而是被更高优先级的配置覆盖了。Composer 加载源的顺序是：命令行 --repository-url > 项目 composer.json 中的 repositories > 全局 config.json。
- 进项目目录后执行
composer config --list | grep repositories，如果输出非空，说明项目级配置存在 - 常见陷阱：Laravel 脚手架模板自带
"repositories": {"packagist.org": false}，这等于禁用了默认源但没给替代源，结果就是Could not find package - 临时验证可运行
composer config --unset repositories && composer clear-cache，再试composer require monolog/monolog -vvv - Docker 或 CI 环境中，
composer config -g写的配置不会持久化，得在构建阶段显式执行该命令
如何确认镜像真正在用
别信“好像快了”，要看实际网络请求路径。最可靠的方式是开调试日志：
- 先清缓存：
composer clear-cache - 执行
composer require monolog/monolog -vvv 2>&1 | grep "Downloading.*packages.json" - 看到
Downloading https://mirrors.aliyun.com/composer/packages.json才算真正落地 - 如果还出现
packagist.org或github.com，说明composer.lock里硬编码了原始 dist 地址，需运行composer update --lock刷新 -
composer diagnose输出中的 “Repo” 行显示的是最终生效地址，但不如日志直观
最容易被忽略的一点：某些老旧 PHP 版本（如 7.0 以下）不支持 SNI，会导致 HTTPS 镜像握手失败；还有些公司内网 DNS 或证书链不全，也会让镜像请求卡住或报 cURL error 60。这时候得换镜像站，或者临时降级用 HTTP（仅限测试环境）。
