parallel-downloads在composer 2.2+已弃用，应改用http-max-concurrent-downloads；它仅全局生效且需配对镜像与缓存清理，否则静默失效。
并发下载失败：parallel-downloads 配置不生效
Composer 2.2+ 默认启用并发下载，但很多人设了 parallel-downloads 却没效果，本质是配置没写对或被覆盖。它只在全局生效，且必须用 composer config -g 设置，项目级 composer.json 里的 config 字段不认这个键。
常见错误：执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（漏了 -g），结果只改了当前项目，而 parallel-downloads 必须全局生效才起作用。
- 正确写法：
composer config -g parallel-downloads 10（推荐值 6–12，过高反而触发镜像限速） - 验证是否生效：
composer config -g parallel-downloads输出应为10，不是null或空行 - 若仍报错
Could not resolve packages或卡在Downloading，说明镜像源本身限流——阿里云镜像对单 IP 并发请求有阈值，超过会返回 429
重试机制被绕过：--retry 参数失效的场景
--retry=3 看似万能，但实际只对特定错误码生效：cURL 错误 6（DNS 失败）、28（超时）、7（连接拒绝）。它对 404、403、Content-Length mismatch 或校验失败完全不重试——这些是“确定性错误”，Composer 认为重试无意义。
典型现象：反复卡在同一包，日志里出现 Failed to decode response: zlib_decode(): data error 或 sha256 hash mismatch，说明缓存已损坏，不是网络问题。
- 先清缓存：
composer clear-cache，重点确认~/.composer/cache/files/下对应包的 ZIP 是否被截断 - 加
--no-cache强制跳过本地缓存，避免复用坏文件 - 若仍失败，换镜像源再试：
composer config -g repo.packagist composer https://packagist.proxy.tencent.com/（腾讯镜像对并发更友好）
HTTP 限速与 timeout 参数冲突
很多人同时设 http-timeout 和 process-timeout，结果发现 http-timeout 毫无作用。因为 http-timeout 只控制单次 HTTP 响应头接收时间，而 Composer 下载大 ZIP 包时，真正卡住的是数据流传输阶段——这由 PHP 的 default_socket_timeout 和 cURL 的 CURLOPT_TIMEOUT 控制，http-timeout 完全不参与。
- 有效做法：调高 PHP 层面的 socket 超时，在
php.ini中设default_socket_timeout = 600 - 命令行临时覆盖：
php -d default_socket_timeout=600 $(which composer) install - 别碰
process-timeout：它管的是脚本执行总时长（如 autoload 生成），和网络无关，设太高反而掩盖真实问题
CI 环境下并发失败的隐藏原因
CI 构建中 composer install 在并发模式下频繁失败，往往不是配置问题，而是构建节点共享出口 IP 导致镜像源限频。阿里云镜像对同一 IP 每分钟请求数有限制，多个并行 job 同时发起请求，极易触发 429。
此时 --retry 和 parallel-downloads 都会失效，因为重试请求仍走同一 IP，限频状态未解除。
- 方案一：CI 中禁用并发，设
composer config -g parallel-downloads 1 - 方案二：用环境变量注入镜像，避免全局配置污染：
COMPOSER_REPO_PACKAGIST=composer=https://mirrors.aliyun.com/composer/ composer install - 方案三：在 CI 脚本开头加随机 sleep（如
sleep $((RANDOM % 3))），错开请求时间点
并发拉取不是越快越好，镜像源的承载能力、本地 DNS 缓存强度、甚至 PHP 进程数都会成为瓶颈。配完 parallel-downloads 后，务必用 -vvv 观察实际并发连接数，而不是只看参数值。
