Composer超时需分层处理：process-timeout控制子进程（如git clone），http-timeout控制HTTP请求（含DNS、TLS等），二者独立且必须同时配置；PHP socket超时和GitHub API限流等底层问题常被误判为网络超时。
process-timeout 和 http-timeout 混用导致无效
很多人以为调高 process-timeout 就能解决所有“超时”，但实际卡在 Downloading https://... 时，真正起作用的是 http-timeout（Composer 2.x）或旧版的 http-basic-timeout。这两个参数完全独立：process-timeout 控制 git clone、unzip 等子进程，http-timeout 控制单次 HTTP 请求的总耗时（含 DNS、TLS、首字节、body 传输）。只改一个，另一层仍会掐断连接。
- 常见错误：执行
composer config -g process-timeout 1200后依然卡在 downloading，却没查http-timeout - 验证方式：运行
composer config -g http-timeout，若无输出说明用默认值 300，弱网下大概率不够 - PHP 底层限制也得同步调：
php -i | grep default_socket_timeout若显示 60，那哪怕设了http-timeout 600，PHP 自己也会在 60 秒后中断 socket
GitHub API 403 被误判为网络超时
日志里出现 https://api.github.com/ 请求失败、返回 403 或静默卡住，不是网络问题，是 GitHub 的未认证 API 限流（每小时仅 60 次）。换镜像源、加 timeout、开代理全无效——因为镜像不转发 GitHub API 请求，这类调用永远直连。
- 典型现象：
composer update卡在 “Loading composer repositories” 阶段，-vvv可见最后请求是GET https://api.github.com/repos/xxx/yyy - 必须配 Personal Access Token：执行
composer config -g github-oauth.github.com，注意域名是github.com，不是api.github.com - Token 权限只需勾选
repo（含public_repo），其他如delete_repo完全不需要，权限过大反而有安全风险
CI 环境中配置丢失或未生效
GitHub Actions、GitLab CI 等容器环境里，composer config -g 写入的配置常被忽略，因为每次 job 启动都是全新容器，COMPOSER_HOME 未显式设置时默认指向临时路径，重启即丢；更隐蔽的是，某些 Composer 版本优先读取环境变量而非 config 文件。
- 常见错误：本地
composer config -g process-timeout 1200有效，CI 中却仍报超时，没检查是否设置了COMPOSER_HOME - CI 必须显式声明：在 job 步骤开头加
export COMPOSER_HOME=/tmp/composer，再运行 config 命令 - 环境变量优先级更高：直接用
COMPOSER_PROCESS_TIMEOUT=2000 COMPOSER_HTTP_TIMEOUT=1200 composer install更可靠，尤其对旧版 Composer - 别漏 PHP 扩展：CI 容器常缺
ext-zip或ext-xml，composer install 会直接退出，根本走不到超时逻辑
设为 0 后仍失败，误以为配置无效
把 process-timeout 或 http-timeout 设为 0 表示禁用超时，但若仍失败，大概率是底层资源瓶颈，不是 Composer 配置问题。
- 内存不足最常见：update 阶段解析锁文件时大量占用内存，
memory_limit默认 128M 远不够，建议 ≥ 1.5G，用php -d memory_limit=2G composer update测试 - Docker 容器被额外限制：比如
docker run --stop-timeout 30或宿主机systemd的TimeoutStopSec会强制 kill 进程，Composer 完全感知不到 - 磁盘 I/O 阻塞：WSL2、Docker for Mac 下 vendor 目录挂载在 NTFS 卷时，生成 autoload files 阶段可能卡死，这不是超时，是系统调用 hang 住
关键点在于：timeout 设置只是兜底手段，真正卡住的原因往往藏在它下面一层——PHP socket 限制、GitHub 认证缺失、CI 环境变量覆盖、或内存/I/O 瓶颈。调参前先看清楚错误发生在哪一阶段，否则容易反复折腾却没碰对地方。
