cn-fast-dl

国内 GitHub 大文件多线程加速下载工具。自动测试并选择最快的国内代理，用 N 个并行 HTTP Range 连接分段下载，再合并成完整文件。

实测：国内网络单连接走代理约 100 KB/s（下载 494MB 要 80 分钟）；用 16 线程并行后合计约 1.6 MB/s，30 秒完成。

• 零依赖（纯 Node.js 内置模块）
• 自动测试代理 + 直连，选最快的通道
• 服务器不支持 Range / 无 Content-Length 时自动降级为单连接
• 分段失败自动重试（指数退避）
• 流式合并，支持多 GB 大文件
• 提供 CLI 和 Node.js 库 API 双入口

原理

国内访问 GitHub 慢，通常不是带宽不够，而是单连接被限速。GitHub 的 Release 文件支持 HTTP Range 头，可以按字节区间分段下载。把一个大文件切成 N 段、用 N 个连接同时下载，总速度 ≈ N × 单连接速度。

单连接:  100 KB/s  →  494MB 需要 80 分钟
16 线程: 1.6 MB/s  →  494MB 只需 30 秒

本工具自动完成：测速选代理 → 分段 → 并行下载 → 重试 → 流式合并。

安装

npm install -g cn-fast-dl   # 全局安装（提供 cn-dl 命令）
# 或
npm install -D cn-fast-dl   # 作为项目依赖
# 或直接使用
npx cn-fast-dl <url> -o out.zip

CLI 用法

cn-dl <url> -o 输出文件 [选项]

| 选项 | 说明 | 默认 | |------|------|------| | -o, --output <path> | 输出文件路径 | 必填 | | -c, --connections <n> | 并行连接数 | 16 | | -p, --proxy <url> | 指定代理前缀（如 https://ghfast.top） | 自动测试选择 | | --no-auto-proxy | 禁用自动选代理，强制直连 | false | | --retries <n> | 分段失败重试次数 | 15 | | -h, --help | 显示帮助 | |

示例

# 下载 GitHub Release 大文件（自动选最快代理）
cn-dl https://github.com/xxx/repo/releases/download/v1.0/big-file.zip -o big-file.zip

# 指定更少的连接（服务器有并发限制时）
cn-dl https://github.com/xxx/file.tar.gz -o file.tar.gz -c 8

# 指定代理
cn-dl https://github.com/xxx/file.bin -o file.bin -p https://ghfast.top

# 非 GitHub 源（如 Ubuntu 官方源）默认直连，不套代理
cn-dl https://releases.ubuntu.com/24.04/ubuntu-24.04-desktop-amd64.iso -o ubuntu.iso

Node.js API

const { download } = require('cn-fast-dl');

await download('https://github.com/xxx/repo/releases/download/v1.0/big-file.zip', {
  output: './big-file.zip',
  connections: 16,
  onProgress: ({ percent, downloaded, total }) => {
    console.log(`进度: ${percent}% (${downloaded}/${total})`);
  },
});
// → { total, downloaded, output }

选项

| 选项 | 类型 | 默认 | 说明 | |------|------|------|------| | output | string | 必填 | 输出文件路径 | | connections | number | 16 | 并行连接数 | | proxy | string | 自动 | 指定代理前缀；否则自动选择 | | autoProxy | boolean | true | 是否自动选代理（GitHub 源） | | timeout | number | 45000 | 单请求超时（ms） | | retries | number | 15 | 分段失败重试次数 | | onProgress | function | - | ({ downloaded, total, percent }) => void |

其他导出

const { proxies, testProxies, pickFastestProxy, isGitHubUrl } = require('cn-fast-dl');

await testProxies('https://github.com/xxx/file.zip');
// → [{ proxy: 'https://ghfast.top', speed: 120000 }, ...] 按速度降序

await pickFastestProxy('https://github.com/xxx/file.zip');
// → { proxy: 'https://ghfast.top', url: 'https://ghfast.top/https://github.com/...', speed: 120000 }

内置代理

自动测速的国内加速代理（按需增删）：

https://ghfast.top
https://gh-proxy.com
https://ghproxy.net
https://gh.llkk.cc
https://github.moeyy.xyz

网络正常时（GitHub 直连可达），工具会自动跳过代理走直连，国内外通用。

故障排查

• 所有通道都失败：检查网络；或手动指定代理 -p https://ghfast.top，也可以换一个代理试试。
• 下载很慢：适当增加连接数 -c 32；某些代理对并发有限制，可降 -c 8。
• 输出文件不完整：工具内置分段完整性校验，不完整的段会自动重下；仍异常时请反馈。

License

MIT