Composer执行install时，看起来只是在下载PHP包，实际可能先访问Packagist元数据，再从代码托管或对象存储下载dist压缩包；选择source安装时还会调用Git。代理只覆盖了元数据域名，就会出现“解析成功，下载阶段失败”。
一、dist和source是两条不同链路
| 模式 | 常见动作 | 网络重点 |
|---|---|---|
| dist | 下载发行压缩包 | 重定向、对象存储、超时和校验 |
| source | 通过Git克隆源码 | Git HTTPS或SSH配置 |
| 元数据 | 读取仓库与版本信息 | Packagist或私有Composer仓库 |
| 插件与脚本 | 运行安装期代码 | 供应链权限与额外网络请求 |
二、Composer通常如何读取代理
Composer运行在PHP CLI环境中，可按版本支持读取常见代理环境变量及绕过规则。变量必须存在于实际执行进程；Web服务器或PHP-FPM的环境与CLI并不相同。CI、容器和systemd服务也各有自己的配置来源。
三、代理认证与目标服务认证要分开
代理407需要处理出口认证；GitHub、GitLab或私有Composer仓库返回401/403，则要检查目标平台令牌与权限。不要把代理密码填入目标服务的认证配置，也不要把访问令牌放到代理URL。
四、auth.json如何安全使用
auth.json可能保存代码托管或私有仓库凭据，应放在适当的用户级或受控项目环境，限制文件权限，并确保不会提交到公开仓库或打包进制品。CI中优先使用秘密变量或平台支持的Composer认证注入。
五、Packagist正常，dist下载为什么超时
Composer解析元数据后，dist地址可能指向另一个代码托管或文件域名，还可能发生重定向。代理白名单、DNS和证书必须覆盖实际地址。日志应记录脱敏后的主机和状态码，不要公开带签名的下载URL。
六、source安装失败为什么要查Git
source模式调用Git，HTTPS远程与SSH远程使用不同代理路径。Composer自身网络成功，不代表Git也配置正确。Git代理层级与清理方法见Git HTTP代理与SSH远程指南。
七、证书错误不要降低secure-http
应检查运行Composer的PHP CLI实际加载的CA文件、OpenSSL配置、系统时间、代理TLS检查和目标证书链。关闭安全HTTP要求或证书验证会降低包来源身份保障，不适合作为正式配置。
PHP CLI与FPM差异及CA检查可参考PHP cURL和Guzzle代理排查。
八、缓存为什么会让问题时好时坏
依赖已在Composer缓存中时，安装可能不访问网络；换一台CI机器或升级版本后又会重新下载。验证时应通过详细输出确认缓存命中与实际请求，不要把开发机一次成功当作新环境证据。共享缓存还需控制写权限和完整性。
九、NO_PROXY适合哪些目标
内部Composer仓库、回环服务和公司代码托管可能需要直连。应按Composer、PHP网络库和Git各自支持的语法验证。一个NO_PROXY值未必能覆盖所有子进程，尤其是source安装调用Git时。
十、插件和脚本为什么需要额外谨慎
Composer插件及包脚本可以在安装期间执行代码。依赖来源与权限应经过审查，CI中使用最小权限，避免为了网络调试随意允许未知插件。代理只能控制路径，不能证明依赖本身可信。
十一、排查流程
- 记录PHP CLI、Composer和Git版本；
- 确认失败在元数据、dist、source还是脚本阶段；
- 检查执行进程中的代理和绕过变量；
- 区分407、目标401、TLS和下载超时；
- 核对重定向后的实际下载主机；
- 在CI或容器中用同一账号复测；
- 清理临时auth、明文密码和诊断日志。
十二、结论
Composer代理问题应沿元数据、dist文件和Git源逐段检查。代理凭据、仓库令牌和证书信任属于不同层；分清失败阶段，才能避免通过关闭安全选项换来一次不可复现的安装。
