Composer install卡在packagist.org是因DNS解析慢、TLS握手失败和CDN节点不可达三重叠加导致直连阻断；应执行composer config -g repo.packagist composer https://packagist.mirrors.huaweicloud.com并clear-cache，再用-vvv验证日志是否命中镜像域名。
为什么 composer install 总卡在 packagist.org？
国内直连 packagist.org 常因网络波动导致超时、404 或 Could not fetch packages 错误，本质是 Composer 默认源被阻断或延迟高。不是你项目写错了，也不是 PHP 版本问题，纯粹是 DNS 解析慢 + TLS 握手失败 + CDN 节点不可达三重叠加。
平滑过渡的关键不是“换镜像”，而是让 Composer 在不改 composer.json、不碰已有 lock 文件的前提下，临时或全局生效新源——否则 composer update 会重算依赖树，可能引入意外版本变更。
- 优先用
composer config -g repo.packagist composer https://packagist.phpcomposer.com（已停用）或当前主流：composer config -g repo.packagist composer https://packagist.mirrors.huaweicloud.com - 华为云镜像稳定、同步及时，且支持 HTTPS 和 Composer 2.x 的完整协议；阿里云镜像（
https://mirrors.aliyun.com/composer/）需注意路径末尾不能带斜杠，否则报Invalid repository type - 切勿直接编辑
~/.composer/config.json手动加repositories—— 容易格式错误，且config -g会覆盖它
如何验证镜像是否真正生效？
执行 composer config -g repo.packagist 只显示 URL，不代表请求真走那里。真正验证得看实际网络行为：
- 加
-vvv参数重跑composer install，搜日志里出现的Downloading https://packagist.mirrors.huaweicloud.com而非packagist.org - 用
curl -I https://packagist.mirrors.huaweicloud.com/packages.json确认返回 200，且Server头含nginx或cloudflare，排除 DNS 污染 - 若仍走原站，检查是否项目级配置覆盖了全局：运行
composer config repo.packagist（不带-g），如有输出就删掉：composer config --unset repo.packagist
composer.lock 文件要不要重新生成？
不用。lock 文件记录的是具体包哈希和版本号，跟源无关。只要镜像同步及时（华为云/阿里云通常 5 分钟内同步），composer install 就能从镜像下载对应 zip 包，校验哈希一致即成功。
立即学习“PHP免费学习笔记（深入）”；
唯一要重生成 lock 的场景：你明确需要升级某依赖，且该依赖在新镜像中存在更高 patch 版本（比如 monolog/monolog 从 2.9.1 到 2.9.2），此时才运行 composer update monolog/monolog —— 否则强行 update 可能升到不兼容的 minor 版本。
- 镜像只是下载通道，不改变语义化版本规则
-
composer install严格按 lock 文件还原，哪怕镜像暂时缺某个旧版本 zip，也会报错而非降级 - 若遇
Package ... has no installation candidates，先确认镜像是否支持你用的 PHP 版本（如 PHP 8.3+ 包可能尚未同步）
团队协作时怎么避免镜像配置冲突？
开发者本地设全局镜像没问题，但 CI/CD 流水线（如 GitHub Actions）必须显式声明镜像源，否则不同环境行为不一致。别指望所有机器都提前配好 config -g。
- GitHub Actions 中，在
composer install步骤前加一行：composer config -g repo.packagist composer https://packagist.mirrors.huaweicloud.com - Docker 构建时，在
RUN指令里嵌入该配置命令，不要 COPY 本地~/.composer/config.json—— 容器无状态，且用户权限可能不匹配 - 禁止在
composer.json里硬编码repositories—— 这会让所有用户强制走该源，无法灵活切换，也违背 Packagist 官方推荐做法
最麻烦的其实是老旧项目用了自定义私有仓库，而镜像只代理官方源。这时得保留原 repositories 配置，再额外加镜像，顺序很重要：packagist 必须是第一个，否则私有包查询会失败。
