适用条件：Composer 2 命令行与可信项目

本文按 Composer 当前官方文档中的 Composer 2 命令行用法核对，适用于 Windows、macOS 和 Linux。先记录 composer --version 与 php --version，并用 php --ini 确认 CLI 加载的配置；网页 PHP 使用的 php.ini 不一定与终端相同。文档滚动更新，具体选项先用本机命令的 --help 确认。

示例在自己信任的项目目录执行，通常不需要管理员或 root 权限。实际下载会消耗网络与磁盘；install 可能写 vendor 和自动加载文件。先保留 composer.json、composer.lock 及已有配置，不把联网排障变成一次无意的全量升级。

先读诊断结果，区分三种下载

三平台终端均可；只在本地查看输出，分享前脱敏
composer --version
php --version
php --ini
composer --no-plugins --no-scripts diagnose -vvv
composer --no-plugins --no-scripts config --list --source
失败阶段或提示重点核对
包列表或元数据请求失败实际仓库地址、代理变量、DNS 与 HTTPS
元数据成功，dist 压缩包失败日志中的下载主机及其网络、认证或限流响应
source / git clone 失败Git 子进程的协议、代理与权限；不能只查 Composer HTTP
PHP 扩展或版本约束不满足运行环境与依赖约束，不属于换节点能修复的问题
证书链错误CLI PHP/Composer 使用的 CA 文件与组织证书策略

diagnose 是诊断，不是实际项目所有依赖都能下载的保证。config --list --source 用于定位设置从哪里来；输出可能包含内部路径和仓库信息，不要原样贴到公开群。只记录必要的来源文件及相关键。

代理变量中的 https 指目标请求，不代表代理必须使用 TLS

Composer 用 http_proxy 处理 HTTP 请求，用 https_proxy 处理 HTTPS 请求。常见本地 HTTP 代理的两个变量值都应为 http://127.0.0.1:端口；不要因为目标仓库是 HTTPS 就把代理 URL 改成 https://。后者表示客户端与代理之间使用 TLS，需要代理本身支持。7890 只是例子，必须替换成当前机器实际 HTTP 或 mixed 端口。

macOS / Linux Bash 或 zsh；仅影响本次诊断
http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890 composer --no-plugins --no-scripts diagnose -vvv
Windows PowerShell；临时设置两个变量，结束后恢复原值
$roxiOldComposerHttp = $env:http_proxy
$roxiOldComposerHttps = $env:https_proxy
try {
  $env:http_proxy = 'http://127.0.0.1:7890'
  $env:https_proxy = 'http://127.0.0.1:7890'
  composer --no-plugins --no-scripts diagnose -vvv
} finally {
  if ($null -eq $roxiOldComposerHttp) {
    Remove-Item Env:http_proxy -ErrorAction SilentlyContinue
  } else { $env:http_proxy = $roxiOldComposerHttp }
  if ($null -eq $roxiOldComposerHttps) {
    Remove-Item Env:https_proxy -ErrorAction SilentlyContinue
  } else { $env:https_proxy = $roxiOldComposerHttps }
}
  1. 比较诊断中同一个 URL 的结果与客户端连接记录。如果目标被 no_proxy 命中，它会绕过代理；保留企业域名需要的绕过项，不要不加区分地清空。
  2. 确认元数据恢复后，再检查原来失败的压缩包域名。不要假设 Packagist 首页可访问就代表全部 dist 下载主机可用。
  3. 如果进入 Git 下载阶段，记录实际协议和子进程错误；HTTP 代理变量不是任意 SSH 连接的通用代理配置。按 Git 的实际传输方式排查，不盲目切换所有依赖到 source。

保留锁文件，做有限的下载验证

在已有 composer.lock 的可信项目中，install 使用锁定版本；没有锁文件时可能解析依赖并创建它。先检查锁文件存在，再使用下面的诊断命令。它会下载依赖到缓存，暂不完成安装；禁用插件和脚本用于缩小问题范围，但某些项目依赖插件提供下载能力，禁用后出现的不同错误不能直接归因于网络。

三平台终端；已有锁文件，下载会产生流量与缓存写入
composer --no-plugins --no-scripts install --prefer-install=dist --download-only -vvv

需要走代理时，将上一节临时环境设置中的 diagnose 命令替换为本节 install 命令，仍使用相同的保存与恢复方式。--prefer-install=dist 表达优先安装形式，不能保证每个依赖都有 dist。--dry-run 是模拟操作，不能替代实际下载验收。不要用 composer update 来测试网络，它会重新求解并更新锁文件。

证书与超时：只调整对应层

  1. 证书错误先看 diagnose -vvv 开头报告的 CA 文件或目录，再核对 CLI 的 php.ini 与可信 CA 部署。需要指定证书包时使用组织确认的 CA 文件，保持 secure-http 和 TLS 验证启用。
  2. process-timeout 控制 Git 克隆等外部进程执行时间；它不是所有 HTTP 下载超时的统一开关。先从日志确定是子进程超时还是 curl 请求超时，再按相应官方说明调整。
  3. 确有 IPv6 路径异常线索且 Composer 使用 PHP curl 扩展下载时，可单次设置 COMPOSER_IPRESOLVE=4 做对照。此设置的适用条件不满足时没有同样效果，不据此长期关闭系统 IPv6。

完成实际安装后再判断是否修复

  1. 有限下载验证成功后，在确认项目插件和脚本可信的前提下，按团队原流程执行 composer install，验证项目能使用依赖；不要把禁用插件的诊断状态当作正式部署完成。
  2. 检查 composer.lock 与 composer.json 没有非预期变动。退出临时环境，恢复本次改动的 CA、代理或超时设置，保留必要且已验证的修复。
  3. 仍失败时报告 Composer/PHP 版本、CLI 配置位置、失败阶段、脱敏主机名与错误；认证或限流问题向对应仓库维护者核实，不公开令牌。