必须配置 Packagist 镜像源，因国内无法稳定访问官方源：DNS 解析慢、TLS 握手不稳定、CDN 缺失，导致 composer install 常卡在“Loading composer repositories”超 5 分钟；阿里云与中科大镜像已全量同步，延迟极低。
composer config -g repo.packagist 这条命令必须执行，否则 90% 的人会在第一次 composer install 时卡死在 “Loading composer repositories with package information” —— 不是网络差，是默认源根本连不上。
为什么必须配镜像，而不是“试试看再说”
packagist.org 的原始域名在国内 DNS 解析慢、TLS 握手不稳定、CDN 节点缺失，不是偶尔超时，而是持续性不可用。实测：未配镜像时，composer install 卡住超过 5 分钟是常态，且不会报错，只停在那不动。
阿里云和中科大镜像已全量同步 packagist，更新延迟 composer.lock 校验），不是“能用就行”的降级方案，而是生产级替代。
全局镜像配置的正确写法（Linux/macOS/WSL）
运行以下命令即可生效，不需要手动编辑 ~/.composer/config.json：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
验证是否成功：
composer config -g repo.packagist
输出应为 https://mirrors.aliyun.com/composer/，而非 https://packagist.org。
- 如果提示
Permission denied，说明当前用户无权写入~/.composer/目录，改用sudo composer config -g ...或先修复目录权限：chown -R $USER ~/.composer - 不要用过时的镜像地址如
https://packagist.phpcomposer.com（该站已于 2023 年下线） - 中科大镜像可作为备选：
composer config -g repo.packagist composer https://mirrors.ustc.edu.cn/composer/
Windows 用户绕过安装器直接配镜像
哪怕你用了 Composer-Setup.exe 图形安装器，它默认也不配镜像。必须手动补这一步：
以管理员身份打开 PowerShell 或 CMD，运行：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
注意：Windows 下 composer config -g 写入的是 %USERPROFILE%\AppData\Roaming\Composer\config.json，路径含空格或中文不影响，Composer 自己能处理。
- 如果提示
'composer' is not recognized，说明 PATH 没生效，重启终端或重新登录 Windows 账户 - 别信某些教程让你改
php.ini或装额外代理——镜像配置纯客户端行为，不依赖 PHP 扩展或系统代理
项目级临时切换镜像的场景和风险
仅当你要验证某个包在原始源下的行为（比如调试镜像同步延迟），才用项目级配置：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
⚠️ 注意：这个命令只影响当前目录下的 composer.json，且会写入项目根目录的 composer.json 中的 repositories 字段。多人协作时容易误提交，引发 CI 失败。
更安全的做法是：全局配好阿里云镜像，需要测原始源时，加 --no-plugins + 临时环境变量：
COMPOSER_REPO_PACKAGIST=https://packagist.org composer install --no-plugins
这样既不污染配置，也不影响其他项目。
真正卡住人的从来不是“怎么配”，而是配完没验证、配错地址、或混用全局/项目级配置导致行为不一致。镜像不是锦上添花的功能，是 Composer 在国内可用的底线。
