Composer怎么设置超时时间_Composer超时配置与调优【详解】

Composer超时必须分两路调：网络下载卡在Downloading https://时调http-timeout，本地命令卡在Installing dependencies或报The process timed out时调process-timeout；二者独立生效，混用或只改其一无效。

遇到Composer超时，很多人的第一反应是“把超时时间调大”。但这里有个关键点常常被忽略：超时问题其实分两种，而且必须对症下药。网络下载卡在 Downloading https://，你得调 http-timeout；如果是本地命令卡在 Installing dependencies 或者直接报错 The process timed out，那该调的是 process-timeout。这两个参数独立生效，混用或者只改其中一个，问题很可能纹丝不动。

卡在 Downloading https://？调 http-timeout

这种情况，问题通常不在Composer本身，而是底层的网络连接等不及服务器响应就放弃了。说白了，是PHP的cURL或者stream扩展在“催命”。典型的错误信息包括 Could not fetch https://repo.packagist.org/packages.json 或者 curl error 28，反复重试几次后最终失败。

• 核心作用：http-timeout 控制所有HTTP请求（无论是拉取元数据 packages.json，还是下载ZIP包）的最大等待时间，默认是300秒。
• 项目级设置：执行 composer config http-timeout 600，这个配置会写入当前项目的 composer.json 文件的 "config" 段落里。
• 全局设置：执行 composer config --global http-timeout 600，这会影响你机器上所有的Composer项目。
• 临时覆盖（优先级最高）：在命令前加上环境变量，比如 COMPOSER_HTTP_TIMEOUT=600 composer install。
• 别被名字迷惑：注意 http-basic 这个配置项，它只管HTTP基础认证，跟超时控制半毛钱关系都没有。
• 底层限制也要看：PHP本身也有套接字超时限制。可以通过 php -i | grep default_socket_timeout 查看。如果这个值太小（比如默认的60秒），即使在CLI模式下也可能提前掐断连接。临时绕过的方法是在调用Composer时指定参数：php -d default_socket_timeout=600 $(which composer) install。

卡在 Installing dependencies 或报 The process timed out？调 process-timeout

这完全是另一码事。错误信息里一定会包含 [RuntimeException] The process timed out.。此时，是Composer启动的子进程（比如执行 git clone、解压 unzip，或者运行项目自定义的脚本如 php artisan optimize）执行时间太长，被系统强制终止了。加上 -v 参数运行命令，通常能看到最后卡住的那条具体指令。

• 核心作用：process-timeout 默认也是300秒，但它只管控子进程的执行时长，跟任何网络HTTP请求无关。
• 项目级配置（最推荐）：执行 composer config process-timeout 1800（设为30分钟），配置会写入当前项目的 composer.json。
• 警惕过时教程：通过 composer config --global process-timeout 进行全局配置的方式在新版Composer中已经失效，别再被老文章误导了。
• 有效的全局设置方式：使用环境变量。在Linux/macOS下：export COMPOSER_PROCESS_TIMEOUT=1800；在Windows下则需设置相应的系统环境变量。
• 临时调试：可以直接在命令中指定，如 composer install --process-timeout=1800 或 COMPOSER_PROCESS_TIMEOUT=1800 composer update。
• 关于禁用：虽然可以设为 0 来禁用超时检查，但极其不推荐。万一遇到Git仓库无法访问或者脚本陷入死循环，进程就会无限期卡住。

怎么验证配置生效？常见失效原因

配置完不放心？运行 composer config process-timeout 或 composer config http-timeout 可以查看当前生效的值。不过，下面这些情况经常导致“明明设了却感觉没用”：

• 配置优先级：如果项目的 composer.json 里已经明确写了 "config": {"process-timeout": 300}，那么全局配置或环境变量是无法覆盖它的。项目级配置的优先级最高。
• 版本兼容性：一些较旧的Composer版本（比如 ^2.0 以下）对 process-timeout 的支持可能不太稳定。建议升级到 ^2.2 或更高版本。
• 别搞错问题：如果错误是 Allowed memory size exhausted，这是内存溢出，得去调整PHP的 memory_limit 或者Composer的 memory-limit 配置，跟 process-timeout 没关系。
• 唯一判断依据：真正的进程超时，异常堆栈里一定会出现 Symfony\Component\Process\Exception\ProcessTimedOutException。这是最可靠的诊断线索。
• 排除脚本干扰：用 --no-scripts 参数跳过所有自定义脚本再试一次。如果问题消失，那基本可以断定是 post-install-cmd 或 post-update-cmd 里定义的脚本执行太慢。

比调超时更关键的事：先换镜像源

对于国内开发者来说，遇到网络超时，一上来就猛调 http-timeout 其实是治标不治本。更根本、更有效的解决方案是切换Composer镜像源。执行这条命令切换到阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。这能极大减少 Could not fetch 这类网络错误，从根本上降低对超时容忍度的依赖。

话说回来，无脑调高 process-timeout 也可能掩盖真正的问题。如果一个脚本稳定需要跑10分钟，那更合理的做法或许是考虑拆分这个脚本，或者为其增加进度反馈机制，而不是简单地允许它无限期运行下去。