composer代理配置是刚需，因packagist官方源国内直连延迟高、tls不稳定、cdn限速或拦截，导致composer install常卡在下载packages.json；需全局配置http-proxy和https-proxy（非proxy），并优先使用腾讯云加速的https://packagist.phpcomposer.com镜像源。
Composer 代理配置不是“可选优化”，而是国内 PHP 开发者绕不开的刚需——没配好，composer install 卡在 Downloading https://packagist.org/packages.json 是常态，不是偶然。
为什么 Composer 默认在国内几乎不可用
Packagist 官方源（https://packagist.org）直连延迟高、TLS 握手不稳定，且部分 CDN 节点对国内 IP 有连接限速或偶发拦截。这不是网络问题，是基础设施地理分布导致的客观事实。
常见错误现象包括：
[Composer\Downloader\TransportException] The "https://packagist.org/packages.json" file could not be downloaded (HTTP/2 400)- 命令卡住超过 2 分钟后报
Connection timed out -
composer update反复重试某一个包，最终失败
配置国内镜像源：优先用 https://packagist.phpcomposer.com
这是目前最稳定、同步及时、无需额外认证的镜像。它由腾讯云 CDN 加速，响应快，且长期维护（截至 2026 年仍为推荐首选）。
执行以下命令一次性全局生效：
composer config -g repo.packagist composer https://packagist.phpcomposer.com
注意几个关键点：
- 必须加
-g（global），否则只对当前目录生效 - URL 末尾不能带
/，否则会报Invalid repository type - 该配置写入
COMPOSER_HOME/config.json（Windows 通常是%USERPROFILE%\AppData\Roaming\Composer\config.json） - 如果之前手动改过
composer.json里的repositories，建议删掉，避免冲突
需要代理时：用 http-proxy 而非 proxy
很多教程写 composer config -g proxy http://127.0.0.1:8080，这是错的——Composer 不识别 proxy 这个 key。
正确写法是：
composer config -g http-proxy http://127.0.0.1:8080
如需 HTTPS 代理（比如公司统一出口网关），再加一行：
composer config -g https-proxy https://127.0.0.1:8080
常见坑：
- 代理地址协议必须与目标一致：
http-proxy对应 HTTP 请求，https-proxy对应 HTTPS 请求；混用会导致 400 或 TLS handshake failed - 若代理需认证，格式为
http://user:pass@127.0.0.1:8080，密码含特殊字符要 URL 编码 - 配完不生效？检查是否被项目级
composer.json中的config覆盖（项目级优先级高于全局）
验证和排障：三步快速确认代理是否真起作用
别只看命令跑通了就以为好了。真正起作用的表现是下载速度明显提升，且日志里出现镜像域名。
执行这三步：
- 运行
composer config -g repo.packagist，输出应为https://packagist.phpcomposer.com - 运行
composer config -g http-proxy（或https-proxy），确认值非空 - 加
--verbose跑一次composer install，观察日志中是否出现Downloading https://packagist.phpcomposer.com/packages.json—— 出现这个，才算真正走通
最容易被忽略的一点：某些企业网络会拦截 .phpcomposer.com 域名，此时必须切回代理模式，并确保代理本身能访问 Packagist 官方源。这时候，镜像和代理不是二选一，而是备选组合。
