ZIP / tarball 下载超时或中断

你会遇到什么

从 GitHub 下载 zip / tarball 反复超时、中断，始终拿不到完整压缩包。下载 80% 断掉、重试还是断，你开始怀疑是包太大——其实多半是链路问题。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

到 GitHub 的下载链路（codeload/github.com）不稳定或带宽差，大文件传输中途断开。这不是包的问题，是通道的问题。

下载的本质是“一个 URL 对应一条通道”：同一份内容在 GitHub 上有多个出口——tarball 走 codeload、raw 文件走 raw 端点、仓库内容走 git 协议。这些出口的域名、CDN 和链路质量都不一样，在墙内表现差异很大：可能 codeload 稳而 raw 超时（本市场实测正是如此）。

所以“下载失败”时，第一反应不该是“包太大/网络全坏”，而是换通道：tarball 断 → 换 git 浅克隆（走 git 协议，只拉最新提交、体积小）；clone 断 → 换 tarball。两个通道互相独立，坏一个不意味着全坏。验证完整性也有固定方法：解压无报错（tarball 流式解压）或目录结构完整（clone）。

这背后的通用原则是：同一资源的多个出口之间互相备份，别在一条坏通道上反复重试。

一步步来

1. 换通道 — 必做

tarball 下载断 → 改 git clone 浅克隆；clone 断 → 改 tarball。两者互换常常能绕过坏链路。

2. 换网络 / 开代理 — 必做

切换网络环境或开代理后重试；错峰重试（避开高峰期）。

3. 离线解压 — 必做

换任意可达的镜像站下载 zip → 手动解压 → 按本地路径方式接入；不依赖 zip 完整性的替代 = 只取 skills 目录（tarball 内含）。

怎么确认修好了

下载完整、解压成功（实测形态）：

curl -sL https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 | tar xz
→ 解压完成无报错（实测 544K / 2.1s）

或 git clone --depth 1 正常结束，目录结构完整。

其它环境的表现

症状

从 GitHub 下载 zip / tarball 反复超时、中断，无法拿到完整压缩包。

原因

到 GitHub 的下载链路（codeload/github.com）不稳定或带宽差；大文件传输中途断开。

解法

1. 换通道：改用 git clone（浅克隆 git clone --depth 1 --branch v6.3.0 https://github.com/obra/superpowers.git）或反向互换。
2. 换网络：切换网络环境 / 开代理后重试；错峰重试。
3. 离线解压：换任意可达的镜像站下载 zip → 手动解压 → 按「症状 6」接入；不依赖 zip 完整性的替代 = 只取 skills 目录（tarball 内含）。