Node.js 实现断点下载器
本文从 HTTP/1.1 Range 分片传输协议(RFC 7233)出发,深入剖析断点续传的协商与一致性校验机制,并基于现代 Node.js 原生模块实现一套支持状态码自适应降级、原子持久化与优雅中断的工业级下载器。
在编写命令行下载工具(如我早期开发的 eva)或处理大文件拉取业务时,网络波动导致的连接中断、弱网环境超时以及意外关闭终端是无法避免的现实问题。
如果一个 2GB 的资源在下载到 99% 时断网,缺乏断点续传机制的下载器就必须“从零重开”,这不仅极度损耗用户体验,更白白消耗宝贵的服务器带宽。
一、HTTP 断点续传协议核心机制 (RFC 7233)
所谓“断点续传”,本质上是客户端与服务端基于 HTTP 协议头完成的一场分片范围协商。
sequenceDiagram
autonumber
actor Client as 客户端 (Node.js)
participant Server as HTTP 服务端
Note over Client: 检查本地发现已有临时分片 file.part (大小 1024 字节)
Client->>Server: HEAD /file.zip
Server-->>Client: 200 OK
Accept-Ranges: bytes
Content-Length: 5242880
ETag: "w/3a8f-abc123"
alt 服务端支持 Range (Accept-Ranges: bytes)
Client->>Server: GET /file.zip
Range: bytes=1024-
If-Range: "w/3a8f-abc123"
Server-->>Client: 206 Partial Content
Content-Range: bytes 1024-5242879/5242880
[返回剩余的二进制流数据]
Note over Client: 以追加模式 (flags: 'a') 将流写入本地临时文件
else 服务端不支持 Range
Server-->>Client: 200 OK
[返回完整的二进制流数据]
Note over Client: 降级为全量覆盖下载 (flags: 'w')
end
1. 协商三部曲:探测、范围请求与响应
- 预检与能力探测(
Accept-Ranges):通过发送HEAD请求获取目标资源的基础元信息。若响应头包含Accept-Ranges: bytes,则证明服务器支持基于字节偏移的局部读取。 - 请求指定字节区间(
Range):客户端根据本地已下载的文件字节数(如1024字节),在后续GET请求中附带请求头:表示“从第 1024 字节开始,请求直到文件末尾的所有数据”。1
Range: bytes=1024- - 分片响应状态码(
206 Partial Content):- 支持断点续传:服务端返回
206 Partial Content,并在响应头中通过Content-Range标明当前切片的起止范围与总大小(例如Content-Range: bytes 1024-5242879/5242880); - 不支持断点续传:服务端会直接忽略
Range头,返回标准的200 OK,并从第 0 字节开始推送完整内容。客户端必须对此做好平滑降级(改为全量覆写)。
- 支持断点续传:服务端返回
2. 避免数据污染的关键:资源一致性校验 (If-Range / ETag)
在断点续传的间隔期内,服务端的文件内容可能已经被重新发布或修改。如果客户端继续拿着旧文件的字节偏移去追加新文件的尾部,最终拼合出的必然是一个彻底损坏的乱码文件。
为了避免这种静默的数据污染,必须引入一致性校验:
ETag/Last-Modified:首次请求时保存资源的实体标签(ETag)或最后修改时间;If-Range:续传时将ETag作为If-Range头的值带上。若资源未变,服务器返回206继续下载;若资源已变动,服务器会自动判定失效并直接返回200全量数据,此时客户端应重新创建文件并从头写入。
二、Node.js 核心机制与工程要点
在 Node.js 中构建断点下载器,核心是围绕 fs 模块与 stream 模块做流转调度:
- 已存在字节探测:使用
fs.promises.stat(partFilePath)获取本地已写入的字节尺寸stats.size,以此确定Range请求的起始偏移量。 - 文件写入模式(
flags: 'a'vsflags: 'w'):- 收到
206 Partial Content时:使用fs.createWriteStream(filePath, { flags: 'a' })以追加模式将流接入文件尾部; - 收到
200 OK时:必须切换为{ flags: 'w' }(或清空旧临时文件),防止将全量数据拼接在旧残片后面造成体积翻倍。
- 收到
- 临时文件(
.part)原子重命名机制:为了防止网络中断留下半成品文件被其他程序误当成完整文件处理,在下载期间所有数据必须写入临时文件(如target.zip.part)。只有当流触发finish/close且完成大小校验后,再调用fs.promises.rename原子重命名为目标文件名。 - 流式背压与安全流管道(
stream.pipeline):早期的.pipe()无法自动处理管道中的双向错误捕获与流销毁,容易引发内存泄漏或文件句柄挂起。现代 Node.js 推荐使用stream.promises.pipeline或标准 Web Streams API。 - 实时进度、瞬时速度与 ETA 计算:
- 瞬时下载速率:固定采样周期(如 1000ms),统计该周期内接收的字节差值: $$\text{Speed} = \frac{\Delta \text{Bytes}}{\Delta t}$$
- 剩余预估时间(ETA): $$\text{ETA} = \frac{\text{TotalBytes} - \text{CompletedBytes}}{\text{Speed}}$$
三、现代 Node.js 原生断点续传下载器实现
下面给出一套无第三方废弃依赖、基于现代 Node.js 内置模块(node:http / node:https、node:fs、node:events)且支持 Range 自动探测、206/200 优雅降级、实时进度/速度广播与 AbortController 中断控制 的完整实现。
1. Downloader.mjs 核心类实现
1 | |
2. 客户端调用示例与终端实时进度条
1 | |
四、历史实现复盘与演进过程
在早期为 eva 编写断点下载模块时,社区流行使用基于 request 库的事件模型构建(当时设计思路如下图所示)。
当时的核心逻辑在于利用定时轮询将事件通过 EventEmitter 广播给 CLI 显示组件(如 ora 旋转框):
1 | |
在 eva 命令行界面中的动态终端呈现效果:

历史设计的不足与现代演进反思
- 上游生态变迁:
request库早在 2020 年就已正式宣布弃用(Deprecated)。现代工程应当拥抱 Node.js 原生的node:http/node:https,或通过fetch+ Web Streams 保持零外部运行时依赖。 - 防范数据损坏的健壮性:早期代码直接写入最终目标路径,如果下载中途被
Ctrl + C强杀,本地留下的半截文件可能直接误导外部解析程序;现代设计必须引入.part临时后缀 + 原子rename机制。 - 缺少预检与状态码分支:早期假设服务端必然支持 Range,如果服务端实际上返回了
200 OK,追加模式(flags: "a")就会导致新旧两份文件堆叠在一起,文件直接报废。新版本必须严格区分206与200状态码。
五、工业级落地的边界条件与避坑要点
- HTTP 416 (Range Not Satisfiable) 陷阱:当本地
.part临时文件的体积因为某种异常(例如之前的下载被服务器强制重定向或写入了 HTML 错误页)大于等于服务端的真实文件大小时,服务端会返回 HTTP 416。遇到 416 时必须主动清空本地损坏的分片,重新发起全量下载。 - CDN 与反向代理的压缩干扰(Gzip / Brotli):如果服务端对大文件开启了动态压缩,响应头可能缺失
Content-Length,或者返回的是压缩流的长度,导致字节偏移与实际解压后的文件脱节。在请求头中显式声明Accept-Encoding: identity可指示服务端不要压缩二进制文件。 - 多连接并行切片(Multi-threading Chunked Download):对于超大文件(如数十 GB),断点续传常与多线程并发结合:预先获取总大小,按照 10MB 分片向不同线程分配
Range: bytes=0-10485759、Range: bytes=10485760-20971519,各个分片独立下载为.part.0、.part.1,最后通过文件流按序合并。
结语
一个健壮的断点续传器不仅是几行 HTTP 头的堆叠,更是一套包含了协议协商预检、状态码自适应降级、数据流背压控制、原子文件状态机以及优雅中断的系统化网络工程实践。
