新加坡远程苹果电脑租赁立即订购
Claude

Claude Code 升级报 Download timed out 的原因与排查步骤

编辑部阅读约 5 分钟

升级 Claude Code 时，安装器在下载新版本二进制这一步报 Download timed out: exceeded the total deadline，claude update 直接失败，本地版本停在旧版。这类失败多数不是版本本身的 bug，而是下载链路、代理继承、残留文件或版本跨度过大导致的。下面按从简到繁的顺序给出可操作的排查流程、不同安装渠道的取舍，以及升级前后的注意事项。

升级 Claude Code 时，命令行工具在下载新版本这一步卡住，最后抛出 Download timed out: exceeded the total deadline，版本号停在旧版不动。无论走官方安装脚本，还是执行 claude update，失败都发生在同一个环节：把对应平台的二进制包完整下载下来并安装。

从实际反馈看，这个问题并没有统一的触发条件。有人同一条命令直接成功，有人重试一次就秒过，也有人从更老的版本（比如 2.1.236）一路升不上来。这说明它大概率不是某个版本自身的缺陷，而是下载环节的环境问题——带宽、代理、中间网络设备、本地残留文件，或者版本跨度过大，都可能让安装器在总超时时间内拿不到完整包。

先分清你遇到的是哪一类失败

三种典型表现，处理思路不完全一样：

  • 安装脚本失败：日志停在 ~/.claude/downloads/claude-<版本>-<平台> install 这一行，随后报超时。说明二进制已经下载或正在下载，安装动作没走完。
  • claude update 失败：提示 Failed to install native update 或 TelemetrySafeError，并建议运行 claude doctor。这是自更新通道拿不到包。
  • 老版本长期升不上去：版本跨度较大时反复失败，重试也无效。这类往往是自更新链路对旧版本不友好，或者本地状态已经不一致。

常见原因

原因 表现 判断方式
瞬时网络抖动 偶发失败，重试即成功 同一命令再跑一次
终端有代理、安装器没继承 浏览器或 curl 正常，升级仍超时 检查代理环境变量是否对子进程可见
中间设备拦截大文件下载 每次都在固定进度附近失败 换网络（如手机热点）对比
下载残留或权限问题 重试总走同一条失败路径 查看 ~/.claude/downloads 目录
版本跨度大 老版本反复失败 全新安装能否成功
磁盘空间不足 下载中断，报错不明确 看剩余空间

排查与解决步骤

第一步：原样重试一次

先不要改任何配置。很多失败只是一次下载抖动，重新执行 claude update 即可。如果第二次立刻成功，后面的步骤都不用做。

第二步：跑官方诊断

claude doctor

诊断报告会给出当前安装方式（原生二进制、包管理器或 npm）、可执行文件路径、版本号和更新渠道。先确认自己是哪一种安装方式，后面选方案才不会走错路。

第三步：清掉下载残留再试

ls -la ~/.claude/downloads
rm -f ~/.claude/downloads/claude-*
claude update

只删下载缓存目录里的半成品文件，不要动 ~/.claude 下的配置、凭据和会话记录。同时确认磁盘空间充足、目录可写，新下载的二进制具备执行权限。

第四步：检查网络与代理

env | grep -i proxy

如果本地依赖代理上网，要注意两点：一是代理变量必须是 export 出去的环境变量，而不是只写在某条命令前，否则安装器派生的子进程拿不到；二是 NO_PROXY 里不要把下载地址误排除或误包含。使用企业网关或带 TLS 检查的安全软件时，还需要让系统信任其根证书，否则下载会中途被切断。

最快的对照实验是换一条出口：手机热点、另一台机器或另一个网络环境。如果换了网络就成功，问题基本锁定在本地出口链路上。

如果本地网络长期不稳，或者希望关掉电脑后 Claude Code 仍能长时间在线跑任务，可以考虑把运行环境放到机房：租用一台整机放在新加坡机房的独享远程 Mac，远程连接使用，网络环境比家用宽带稳定，适合长时间挂着 AI 工具。这只是可选做法之一，本地能稳定升级就不必折腾。

第五步：换安装渠道

自更新走不通时，换一种安装方式来覆盖旧版本，往往比继续死磕更省时间：

  • Homebrew：先 brew update，再升级对应的包，包名以本地 brew list 显示为准。适合长期用包管理器统一管理工具链的人。
  • npm 全局安装：如果原本是通过 npm 安装的，用全局安装最新版覆盖即可，具体包名与命令以官方文档为准。
  • 重跑官方安装脚本：适合原生二进制安装的情况，直接覆盖安装。

取舍上，包管理器方式升级路径清晰、可回退，但版本可能略滞后于最新发布；官方脚本和自更新最快，但对网络要求更直接；npm 方式灵活，但要注意全局路径与原有二进制不要同时存在，避免 claude 指向旧文件。

第六步：版本跨度过大时全新安装

如果从很早的版本一路升不上来，先备份再重装：

  1. 备份 ~/.claude 下的配置与自定义设置，以及 MCP 相关配置。
  2. 卸载旧的原生二进制，确认 which claude 不再指向旧路径。
  3. 用官方安装脚本全新安装。
  4. 恢复配置，运行 claude doctor 和 claude --version 校验。

注意事项

  • 升级前先备份 ~/.claude，尤其是配置和登录状态。
  • 不要在正在跑长任务时升级，避免进程被替换导致任务中断。
  • 只从官方渠道获取安装包，不要用第三方转存的二进制，来源不明的可执行文件风险很高。
  • 如果所在网络对境外下载有额外限制，不要尝试绕过管控，改用合规的公司网络、云主机或机房环境完成安装。
  • 具体命令、包名和版本号会随发布变化，操作前以官方最新文档为准。

小结

这个报错的字面意思就是「下载总时长超限」，所以排查顺序应该是：先重试，再看诊断确认安装方式，然后清残留、查代理和出口网络，最后换安装渠道或全新安装。绝大多数情况在前三步就能解决；反复失败且换网络无效的，通常需要换一种安装方式，而不是继续等自更新。

Claude Code网络排查升级失败下载超时Homebrew

相关文章