Composer代理必须同时配置http-proxy和https-proxy，且均以http://开头；缺一则因Packagist全量走HTTPS导致“Loading composer repositories”静默卡住，验证需用composer install -vvv观察Proxy CONNECT日志。

composer config -g http-proxy 和 https-proxy 必须同时设置

只配 http-proxy，composer install 会卡在 “Loading composer repositories”，因为 Packagist 全量走 HTTPS，而 http-proxy 完全不处理 HTTPS 请求。必须两条命令都执行，且值都用 http:// 协议开头：

• composer config -g http-proxy http://127.0.0.1:7890
• composer config -g https-proxy http://127.0.0.1:7890
• 代理地址末尾不能带 /（http://127.0.0.1:7890/ ❌）
• 含特殊字符的密码需 URL 编码，例如 pa@ss/word → pa%40ss%2Fword
• Windows 下若提示 Could not write to file，检查 %APPDATA%\Composer\config.json 是否可写

代理和镜像源不能混用

设了 repo.packagist 镜像，http-proxy 和 https-proxy 就会被完全忽略；开了代理，镜像配置就形同虚设。现象是：明明配了腾讯云镜像，却仍卡在元数据加载阶段，日志里既没出现镜像域名，也没 Proxy CONNECT。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• 要走代理，先清空镜像：composer config -g --unset repo.packagist
• 要走镜像，就别配代理，直接用：composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/（注意末尾 /）
• 验证镜像是否生效：composer config -g repo.packagist 输出必须是完整 JSON，如 {"type": "composer", "url": "https://mirrors.cloud.tencent.com/composer/"}

dist.zip 下载不走 proxy 配置，得单独处理

composer config -g repo.packagist.org.proxy 只代理元数据请求（如 packages.json），对 dist.url 指向的 ZIP 包下载完全无效。你看到 Downloading https://codeload.github.com/...，说明代理根本没覆盖到这一步。

• 真正卡顿的是 ZIP 下载，不是元数据——国内访问 codeload.github.com 常见 TLS 超时、DNS 解析慢、连接重置
• 个人开发推荐用 ghproxy.com 类反向代理，在 composer.json 中为包显式重写 dist.url，例如：
  

  "dist": {"url":"https://ghproxy.com/https://codeload.github.com/laravel/framework/zip/refs/tags/v10.48.12"}

• 企业场景建议部署 satis 或 toran proxy，把 ZIP 缓存到内网，让 composer.lock 中的 dist.url 自动指向内网地址
• --repository 参数对已生成的 composer.lock 无效，必须删掉 lock 文件再跑 composer install --repository=...

验证代理是否真起效，别信 config --list

composer config -g --list 显示有字段，不代表网络请求真走代理。真实行为要看调试日志和底层复现。

• 先清缓存：composer clear-cache
• 加详细日志运行：composer install -n -vvv 2>&1 | grep "Proxy CONNECT\|Downloading"
• 看到 Proxy CONNECT 行 → 代理隧道已建立 ✅
• 看到 Downloading https://packagist.org/... 但无 Proxy CONNECT → 仍在直连 ❌
• 用 curl 单独验证：curl -x http://127.0.0.1:7890 -I https://packagist.org/packages.json，根据返回码快速定位问题（407 / Connection refused / 502）

代理配置最易被忽略的点是：HTTPS 流量必须由 https-proxy 字段触发 CONNECT 隧道，而这个字段的协议头必须是 http://，哪怕你的代理服务监听的是 TLS 端口——填成 https:// 或漏协议头，都会静默失效。