如何通过Composer排查无法连接到Packagist的问题？

本文共计932个文字，预计阅读时间需要4分钟。

此命令非常常见，用于检查`composer`配置的问题。它仅连接到+3C代码块+https://packagist.org+3C代码块+，并检查你的`composer.json`文件中的镜像源和`COMPOSER_REPO_PACKAGIST`环境变量。如果它失败，可能是因为你日常安装的包存在失败。具体来说，它会告诉你：

验证镜像是否真生效，别信 diagnose，直接跑：

• composer show -p | head -5 —— 它走当前实际配置，能拉出包列表就说明镜像通了
• 临时让 diagnose 测镜像：先 composer config --global --unset repos.packagist，再运行 composer diagnose
• 某些企业镜像会静默丢弃非白名单 User-Agent（比如 Composer/2.x），这时 curl -A "Composer/2.x" https://mirrors.aliyun.com/composer/packages.json 才能复现真实行为

换了镜像源还是连不上，缓存和项目级配置在干扰

镜像配完不生效，90% 是因为缓存没清，或项目级配置覆盖了全局设置。

• 必须执行 composer clear-cache —— 否则 Composer 可能从旧缓存读失效 URL
• 检查全局是否生效：composer config -g repo.packagist，应输出类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
• 检查项目级有没有冲突：composer config repo.packagist（不加 -g），如果返回非空，说明 composer.json 里硬写了 repositories，优先级更高
• 清华镜像 URL 必须带末尾斜杠：https://mirrors.tuna.tsinghua.edu.cn/composer/，少一个 / 就是 404

curl -v https://packagist.org/packages.json 卡住，怎么分层定位？

别跳过这步。所有“连不上”的表象，本质都卡在 DNS、TCP、TLS、HTTP 四层中的某一层。

• 如果 ping packagist.org 返回 unknown host → DNS 解析失败，换 DNS（如 8.8.8.8）比调超时更直接
• 如果 ping 通但 curl -v 卡在 Trying xxx.xxx.xxx.xxx... → TCP 连接被防火墙/代理拦截，手机热点一试便知
• 如果卡在 TLS handshake 或报 SSL certificate problem → 系统 CA 证书过旧，或公司中间人代理注入了自签名证书；不要设 disable-tls true，改用 sudo apt install ca-certificates 或导出企业根证书加到 openssl.cafile
• 如果返回 HTML 页面（比如登录页、防火墙提示）→ 网络劫持，不是 Composer 的问题

“Loading composer repositories” 卡死，http.timeout 不起作用？

这个阶段卡住，大概率不是 HTTP 超时，而是第二步 git clone 在后台触发了——而 http.timeout 对它完全无效。

• http.timeout 只控制元数据请求（如 packages.json），单位秒，可设为 600： composer config -g http.timeout 600
• git clone 的超时由 Git 自己管，需单独配置：git config --global http.postBuffer 524288000 和 git config --global http.lowSpeedLimit 0
• 若错误里有 cURL error 28，但 curl -v 正常 → 基本确定是 git clone 阶段卡住，不是 Composer 配置问题
• 某些镜像同步延迟严重，packages.json 返回 200 但内容为空或格式错，导致后续解析失败；此时 composer clear-cache + 换镜像（如从阿里云切到腾讯云）更有效