Composer install/update 卡住时应优先调高 process-timeout（如 --timeout=3000）或换用国内镜像源，而非设为0；其超时机制不解决 GitHub 限流问题，且配置优先级为命令行 > 项目 composer.json > 全局配置。

Composer install/update 卡在 downloading 或 hanging 怎么办

默认超时是 300 秒（5 分钟），遇到大包、网络抖动或镜像同步延迟时，composer install 或 composer update 很容易直接中断报错：file could not be downloaded: failed to open stream: Connection timed out。这不是命令写错了，是连接等不及就断了。

实操建议：

• 临时延长超时：加 --timeout=3000 参数（单位秒），比如 composer update --timeout=3000
• 永久生效：在项目根目录的 composer.json 里加配置项：

  "config": {
    "process-timeout": 3000
  }

• 全局设置（慎用）：运行 composer config -g process-timeout 3000，会影响所有项目

process-timeout 和 github-oauth timeout 有啥区别

process-timeout 控制的是整个命令执行周期（包括解析依赖、下载、解压、脚本运行等），而 GitHub 的 github-oauth token 超时是另一回事——它只影响访问 GitHub API 的鉴权有效期，和下载包本身不直接相关。但如果你用的是私有 repo 或频繁触发 GitHub 限流，github-oauth 配置不当会导致 403 rate limit exceeded，看起来像“超时”，其实是认证失败。

常见混淆点：

Academic Composer Upload

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

下载

• process-timeout 不解决 GitHub 限流问题；要解决限流，得配 github-oauth token 到 auth.json 或全局 config
• 设再高的 process-timeout，也救不了被 GitHub 拒绝的请求
• 国内用户常把镜像源响应慢误判为“超时”，其实换源（如 https://packagist.phpcomposer.com 或 https://mirrors.aliyun.com/composer/）比调 timeout 更有效

timeout 设太大反而会出问题？

设成 0 表示无限等待，听起来安全，实际很危险：一旦网络卡死、DNS 解析失败或镜像源彻底不可用，composer 就会一直 hang 住，不报错也不退出，CI/CD 流水线可能因此卡住几小时。

更稳妥的做法：

• 生产环境 CI 中，推荐显式设为 1800（30 分钟）并配合超时监控，而不是 0
• 本地开发设 3000 足够，再大意义不大——真要下 50 分钟，大概率是源或网络出了问题，该查代理或换镜像
• 某些共享主机限制 PHP max_execution_time，即使 Composer timeout 设再高，也会被 PHP 层强制 kill，此时需同步调整 php.ini 中的该值

为什么改了 config 还是超时？优先级顺序搞清

Composer 读取 timeout 配置是有明确优先级的：命令行参数 > 项目 composer.json > 全局 auth.json > 默认值。如果命令里没加 --timeout，但项目里写了 "process-timeout": 60，那它真就只给你 60 秒——很多人改了全局 config 却忘了项目里有个更低的值在覆盖。

排查步骤：

• 运行 composer config process-timeout 查当前项目生效值
• 运行 composer config -g process-timeout 查全局值
• 确认是否在 composer.json 的 config 块里硬编码了低值，删掉或改高
• 注意：有些老旧版本 Composer（process-timeout 支持不一致，升级到 composer self-update 最新版可避免兼容性坑

网络不稳定时 timeout 只是表象，真正要盯的是源、DNS、代理链路。调数值前，先 ping packagist.org、curl -I https://packagist.org/packages.json 看看底层通不通。