down

一个基于 Node.js 的多线程下载管理器，支持分片并发、断点续传、自动降级与进度条显示。命令行名称为 down，可直接使用 down 进行下载。

特性

- 多线程分片下载（支持 HTTP Range），按偏移写入，文件内容不乱序。
- 自动能力探测：检查 content-length 与 accept-ranges，不支持则自动降级为单线程下载。
- 断点续传：下载过程中生成并更新 output.down.meta.json 元数据文件，重新运行可从未完成位置继续。
- 预分配文件大小：减少磁盘碎片，提高写入稳定性。
- 进度显示：总进度条（总体 MB/百分比）、每个线程进度条、分片完成统计。
- 稳定性增强：Keep-Alive 连接、请求超时与重试策略（默认 3 次重试）。
- 完成后校验：下载结束时校验输出文件大小与期望是否一致。
- 失败清理：下载失败时自动清理 0B 空文件，保留元数据以便继续下载。

安装

- 全局安装（示例）：pnpm i -g down 或 npm i -g down
- 项目内安装：pnpm add down 或 npm i down

使用

基础用法（发布后全局命令为 down）：

``
down [options]
`

常用参数：

- -o, --output 指定输出文件名（默认从 URL 路径推断）。
- -t, --threads 下载线程数，范围 1–20，默认 3。
- -d, --directory 下载目录，默认当前目录。
- -T, --timeout 连接/首字节等待超时（毫秒），下载过程中不限制，默认 600000。

示例：

- down https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
- down http://ipv4.download.thinkbroadband.com/10MB.zip -t 6 -d ./downloads
- down https://example.com/file.zip -o myfile.zip

$3

| 选项 | 简写 | 描述 | 默认值 |
|------|------|------|--------|
| --output | -o | 输出文件名 | 从 URL 自动推断 |
| --threads | -t | 下载线程数 (1–20) | 3 |
| --directory | -d | 下载目录 | 当前目录 |
| --timeout | -T | 连接/首字节等待超时（下载开始前） | 600000 |
| --version | -V | 显示版本信息 | - |
| --help | -h | 显示帮助信息 | - |

进度显示

下载过程中会显示：
- 总进度（已下载/总大小，百分比）
- 每个线程的下载进度和速度
- 分片完成统计

示例输出：

`
总进度 |██████████████████░░░░░░░░| 42% | 12.34/29.00MB
Thread 1 |███████████░░░░░░░░░░░░| 65% | 4.22/6.50MB | 速度: 1.20MB/s
Thread 2 |██████░░░░░░░░░░░░░░░░| 35% | 2.28/6.50MB | 速度: 测量中
分片完成 |█████░░░░░░░░░░░░░░░░| 30% | 已完成: 3/10个分片
`

断点续传说明

- 下载时会在同目录生成 output.down.meta.json（例如 downloads/file.zip.down.meta.json），记录每个分片的 start/end/downloaded/completed。
- 重新运行同一 url 与同一 threads 时，会自动从未完成的位置继续下载。
- 若修改了 threads、url 或服务器返回的总大小发生变化，元数据会被重新初始化，无法直接续传。
- 想强制重新开始：删除对应的 .down.meta.json 文件或更换输出路径/文件名。

实现与行为

- 能力探测：先发起 HEAD 检查 content-length 与 accept-ranges；失败或缺失时回退为短暂 GET 探测；不支持则自动单线程。
- 分片规划：按总大小与线程数等分，最后一片补齐；每片记录 start/end/downloaded/completed。
- 写入方式：预分配文件大小后，按偏移以 r+ 模式直接写入目标文件，无需后续合并。
- 元数据：保存在 <输出文件>.down.meta.json；下载过程中约每 256KB 刷新一次；成功后自动删除元数据文件。
- 覆盖策略：若输出文件已存在将被覆盖；如需保留旧文件，请使用 -o 指定新文件名或调整 -d 目录。
- 校验：当服务器返回总大小时，下载完成后进行大小校验并提示不一致情况。
- 退出码：成功退出码为 0，失败为 1。

性能与调优

- 线程建议：一般 3–6 较为稳妥；局域网/CDN可增至 8–12；高延迟或受限网络建议 2–4。
- 服务端限速/并发限制：若出现 429/503 或频繁断流，请降低线程数或稍后重试。
- 连接复用：启用 Keep-Alive 以减少握手开销；适度提升线程可更充分利用带宽。
- 磁盘空间：预分配会一次性占用目标文件总大小，确保磁盘空间充足。

限制与注意事项

- 不支持 Range 或未知长度时，将无法并发与断点续传，工具会自动单线程以保证完成。
- 续传假设远端内容未变化：当前未校验 ETag/Last-Modified；若内容变更可能导致不一致，必要时删除 .down.meta.json 后重新下载。
- 某些代理/网关会移除 Accept-Ranges 或阻断 206 响应；遇到此类环境建议使用 -t 1。
- HTTPS 证书问题会导致失败：请更换下载源或更新系统根证书。
- 校验建议：暂未内置校验参数，建议使用 shasum -a 256 进行完整性验证。

帮助输出示例

`
Usage: down [options]

A powerful multi-threaded download manager

Arguments:
url URL to download

Options:
-o, --output Output filename
-t, --threads Number of download threads (default: "3")
-d, --directory Download directory (default: current working directory)
-T, --timeout Connect/first-byte timeout in milliseconds (default: "600000")
-V, --version output the version number
-h, --help display help for command

示例:
$ down https://example.com/file.zip
$ down https://example.com/file.zip -o myfile.zip
$ down https://example.com/file.zip -t 10 -d ./downloads
`

代理与网络建议

- 如需通过代理下载，请按需配置系统或网络代理工具。
- 若遇到证书或网络异常，可关闭代理或更换支持 Range 的链接。

Node 版本

- 要求 Node >= 14，建议使用 Node 18+ LTS。

开发与本地调试

- 本地直接运行：node bin/cli.js -t 4 -d ./downloads
- 或全局链接测试：
- pnpm link --global
- 之后可直接使用 down 测试。

常见问题

- 显示“服务端不支持分片或无法获取长度，降级为单线程下载”：服务器未返回 content-length 或不支持 Range，工具会自动降级，确保稳定完成。
- 下载失败留下了 0B 空文件：工具会自动清理 0B 文件；若残留可手动删除。部分失败情况下会保留 .down.meta.json 以便续传。
- 如何判断链接是否支持分片：curl -I | grep -i 'accept-ranges\|content-length'。

许可证

MIT

更新日志

$3


- 切换 HTTP 客户端为 got，启用 Keep-Alive
- 修复并发写入：按文件偏移写入，避免乱序
- 能力探测：检测 content-length 与 accept-ranges，不支持自动降级单线程
- 断点续传：生成/更新 .down.meta.json` 元数据，自动从已下载偏移续传
- 预分配文件大小：减少磁盘碎片，提高写入稳定性
- 进度展示：总进度条、分线程进度条、分片完成统计
- 完成后校验与失败清理：校验输出大小；失败时清理 0B 文件

$3

- 初始版本发布
- 支持多线程下载
- 命令行界面
- 实时进度显示