必须同时配置http-proxy和https-proxy，且均以http://开头并带明确端口；只配其一会导致https请求直连失败，表现为卡在“loading composer repositories”或curl error 7。
composer config -g http-proxy 和 https-proxy 必须同时设
只配 http-proxy，composer install 仍会卡在 “Loading composer repositories”，因为 Packagist 全量走 HTTPS，而 Composer 对协议是严格分流的：http-proxy 只处理 HTTP 请求，https-proxy 才负责建立 CONNECT 隧道。漏掉任一字段，HTTPS 请求就 fallback 到直连，结果是静默超时或 cURL error 7。
正确写法永远是：
composer config -g http-proxy http://127.0.0.1:8080 composer config -g https-proxy http://127.0.0.1:8080
注意：https-proxy 的值必须以 http:// 开头，哪怕代理本身监听 TLS 端口——这是 Composer 的硬性约定，填 https:// 或不带协议都会失效。
- 密码含
@、/、:必须 URL 编码，例如pa@ss/word→pa%40ss%2Fword - 验证是否生效：运行
composer config -g --list | grep -E "(http|https)-proxy"，两行都得有且格式正确 - Windows 下若提示 “Could not write to file”，检查
%APPDATA%\Composer\config.json是否存在且可写
系统级 HTTP_PROXY 环境变量对 Composer 无效
别指望在 shell 里 export HTTP_PROXY=http://127.0.0.1:8080 就能让 Composer 自动走代理——它明确忽略所有系统环境变量，只认自己配置里的 http-proxy 和 https-proxy 字段。这个设计不是疏忽，而是为了隔离网络策略与 shell 环境，避免 CI/CD 或容器中出现不可控透传。
常见误操作：
- 在 GitHub Actions 的
env:块里设HTTP_PROXY，但没配composer config→ 代理不生效 - 用
sudo composer install导致环境变量丢失 → 应该先sudo -E composer install（保留环境），但更稳妥的是直接全局配 proxy - 在 Dockerfile 里
ENV HTTP_PROXY=...后直接跑composer install→ 必须补上composer config -g两行
NTLM 代理或公司内网代理需要中转工具
Composer 原生不支持 NTLM 认证。如果你的公司代理返回 407 Proxy Authentication Required 或 Unable to connect to http://repo.packagist.org，说明它要求域账号登录，而 Composer 没法处理。
必须引入本地中转代理，比如：
-
cntlm：Windows 下最常用，配置好域信息后监听127.0.0.1:3128，再让 Composer 连这个地址 -
px：跨平台替代方案，支持自动检测 NTLM 并转发 - 验证中转是否成功：用
curl -x http://127.0.0.1:3128 -I https://packagist.org/packages.json，看到HTTP/2 200才算通
别尝试改 Composer 源码或加 --no-ssl 参数绕过——这解决不了认证问题，反而暴露安全风险。
镜像源比代理更可靠，优先用 composer config -g repo.packagist
90% 的国内用户遇到的 “下载超时”“卡在 Downloading” 其实不是代理问题，而是根本连不上 packagist.org。与其反复调试代理，不如直接切阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
验证是否生效：composer config -g repo.packagist 输出应为完整 JSON，包含 "url": "https://mirrors.aliyun.com/composer/"。
镜像和代理本质不同：
- 镜像解决路径远（从境外 CDN 切到国内节点）
- 代理解决网络不可达（但需 HTTPS 透传、证书信任、认证兼容等多重条件）
- 多数企业内网已部署私有镜像，此时配代理纯属多余
如果之前设过其他镜像（如腾讯、华为），先清理：composer config -g --unset repos.packagist，再设新地址。
