文件续读为什么会拼坏:Node.js HTTP Range 实战

用零依赖 Node.js 和浏览器实现单区间读取,逐项处理偏移、完整响应回退与版本校验,并以十九项本地测试说明验证范围及生产迁移边界。

从一个很小的错误开始

一个下载按钮已经拿到文件前十个字节,网络断开后再从第十个字节继续读,看起来只需把两次响应拼起来。上线以后却出现偶发文件损坏:服务端已经换成新文件,客户端仍保留旧文件的开头;或者服务器忽略了范围请求,返回整个文件,前端却把完整内容追加到旧片段后面。两种情况都可能收到成功的 HTTP 状态,不能只用 response.ok 判断续读成功。

本文把问题收缩到一个可以逐字节检查的实验:服务端保存三十六字节固定内容,浏览器先取前十字节,再获取剩余部分。我们关心三个结果:收到精确区间就拼接,收到完整版本就替换,收到错误就停止。本例不做视频播放器,也不实现磁盘持久化下载器。这样可以把偏移、版本和响应检查讲清楚,再讨论迁移到真实文件服务时必须补上的能力。

截至 2026 年 11 月 10 日,本文核对了 HTTP Semantics、MDN 范围请求说明及 Node.js 文件读取文档。实际执行环境为 Node.js v24.22.1,代码只使用内置模块,无 npm 依赖。它是一篇协议实现实验,不把某个已有多年的请求头包装成新发布功能。

先约定服务端究竟支持什么

实验只开放固定的 /file 路径,支持 GET 与 HEAD。GET 可以携带一个 bytes 区间;多个区间、未知单位、无法解析的语法都忽略 Range,返回完整内容。这里有意不支持 multipart/byteranges,避免把多段 MIME 封装、边界分隔符和长度计算混进第一次实验。忽略请求头不代表请求失败,客户端必须接受服务端返回二百状态的可能性。

有效范围的两端都包含在结果内,因此零到九恰好是十字节。省略结束位置表示一直读到文件末尾;省略起点表示读取末尾指定长度。结束位置超过文件长度时截断到末尾。起点已经越过末尾,或者后缀长度为零,则返回四百一十六,并说明当前完整长度。倒置区间属于无效语法,本例选择忽略,不能把“无法解析”和“语法有效但没有交集”混成同一种情况。

这些分支对应的状态分别是 200、206 和 416。MDN 对三者及完整响应回退作了直接说明,读取部分内容和传输时分块编码也不是同一层概念。MDN:HTTP range requests

HEAD 不返回响应体,本例也不会因为它带了 Range 就改成部分响应。服务端明确给出完整文件长度,让探测请求不会与实际 GET 的字节范围混淆。总请求头限制为四千零九十六字节;单个 Range 值超过二百五十六字符时忽略,不尝试解析极长整数。更大的请求头会先受到 Node HTTP 解析器限制,并非都能进入应用层回退分支。

解析数字时先使用 BigInt,比较并截断后才转成 Number。原因不是实验文件很大,而是客户端可以传来超出安全整数范围的十进制文本。如果先转浮点数,两个不同偏移可能变成同一个数,范围检查便建立在错误输入上。我们的数据最多八 MiB,最终合法偏移足够小,转换才是安全的。

一个完整的服务端

把下面内容保存为 server.mjs。服务工厂复制传入 Buffer,然后计算 SHA-256 作为强实体标签。外部修改原始输入不会改变已经提供服务的快照,标签和发送字节始终来自同一份内容。这里明确接受内存成本,目的是让版本一致性容易验证。不要删除大小限制后直接加载几十 GiB 文件;那会把一个小型协议实验变成内存事故。

import http from 'node:http';
import { readFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import { fileURLToPath } from 'node:url';

export function selectRange(value, size) {
  if (!value || value.length > 256) return null;
  const m = /^bytes=(\d*)-(\d*)$/i.exec(value.trim());
  if (!m || (!m[1] && !m[2])) return null;
  const n = BigInt(size);
  let start, end;
  if (!m[1]) {
    const suffix = BigInt(m[2]);
    if (suffix === 0n || n === 0n) return false;
    start = suffix >= n ? 0n : n - suffix;
    end = n - 1n;
  } else {
    start = BigInt(m[1]);
    end = m[2] ? BigInt(m[2]) : n - 1n;
    if (m[2] && end < start) return null;
    if (start >= n) return false;
    if (end >= n) end = n - 1n;
  }
  return { start: Number(start), end: Number(end) };
}

export function makeServer(input, page = '<p>Range demo</p>') {
  const data = Buffer.from(input);
  if (data.length > 8 * 1024 * 1024) throw new Error('demo limit: 8 MiB');
  const etag = '"' + createHash('sha256').update(data).digest('hex') + '"';
  return http.createServer({ maxHeaderSize: 4096 }, (req, res) => {
    res.setHeader('Cache-Control', 'no-store, no-transform');
    res.setHeader('X-Content-Type-Options', 'nosniff');
    if (!['GET', 'HEAD'].includes(req.method)) {
      res.writeHead(405, { Allow: 'GET, HEAD' });
      return res.end();
    }
    if (req.url === '/') {
      res.setHeader('Content-Type', 'text/html; charset=utf-8');
      return res.end(req.method === 'HEAD' ? undefined : page);
    }
    if (req.url !== '/file') { res.writeHead(404); return res.end(); }
    res.setHeader('Content-Type', 'application/octet-stream');
    res.setHeader('Accept-Ranges', 'bytes');
    res.setHeader('ETag', etag);
    let range = null;
    if (req.method === 'GET' &&
        (!req.headers['if-range'] || req.headers['if-range'] === etag)) {
      range = selectRange(req.headers.range, data.length);
    }
    if (range === false) {
      res.writeHead(416, { 'Content-Range': `bytes */${data.length}`, 'Content-Length': 0 });
      return res.end();
    }
    const body = range ? data.subarray(range.start, range.end + 1) : data;
    res.setHeader('Content-Length', body.length);
    if (range) {
      res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${data.length}`);
    }
    res.writeHead(range ? 206 : 200);
    res.end(req.method === 'HEAD' ? undefined : body);
  });
}

if (process.argv[1] === fileURLToPath(import.meta.url)) {
  const page = await readFile(new URL('./index.html', import.meta.url), 'utf8');
  const data = Buffer.from('0123456789abcdefghijklmnopqrstuvwxyz');
  const server = makeServer(data, page);
  server.requestTimeout = 15_000;
  server.headersTimeout = 10_000;
  server.listen(3000, '127.0.0.1', () => console.log('http://127.0.0.1:3000'));
}

上面的实现有一个刻意保留的范围:它不是完整通用静态服务器。除 If-Range 外,没有实现 If-Match、If-None-Match 等前置条件,也没有目录路由、鉴权、缓存协商和跨域配置。示例页面不会发送这些额外条件。no-store 用来减小浏览器缓存对实验观察的影响,并不意味着生产环境可以省略条件请求语义。接入通用客户端前应使用成熟静态资源组件,或补齐这些功能和对应测试。

有些教程只写一个长度与修改时间组成的标签。它是否足以作为强校验器,取决于存储系统能否保证相同标记对应完全相同的表示。本例不依赖这一假设,启动时直接对实际字节计算摘要,且运行期间不修改这份内容。摘要不是鉴权凭证,也不防止服务器本身被篡改;它只承担版本比对角色。

续读时必须检查版本

客户端第一次取得片段后保留强 ETag,第二次把它放入 If-Range。相同标签允许继续返回区间;标签不同就忽略范围,返回当前完整表示。旧片段此时必须丢弃。弱标签不满足这里的强比较要求,本例对弱标签、旧标签或日期形式统一走完整响应路径;服务端没有提供 Last-Modified,示例客户端也不会自行构造日期校验器。

与修改表单的并发控制相比,这里的危险点在字节组合:第一段与第二段各自都可能合法,但两者属于不同版本。即使最终长度正确,内容也可能损坏。只有先确认版本和区间,再决定替换还是追加,才能避免“状态成功、文件错误”。HTTP 对 If-Range 的不匹配回退及强比较规则有明确规定。RFC 9110,第 13.1.5 节

下面是完整 index.html,与服务端放在同一目录。按钮点击后先读取十字节,再续读剩余二十六字节。代码检查第一段与第二段的实际长度,同时核对 Content-Range。输出使用 textContent,不把服务端返回内容当成 HTML 执行。整个实验同源运行,不需要额外设置 CORS。

<!doctype html><meta charset="utf-8"><title>字节范围实验</title>
<button id="load">读取前后两段</button><pre id="out"></pre>
<script type="module">
const button = document.querySelector('#load');
const out = document.querySelector('#out');
button.onclick = async () => {
  button.disabled = true;
  try {
    const first = await fetch('/file', { headers: { Range: 'bytes=0-9' } });
    if (first.status !== 206 || first.headers.get('Content-Range') !== 'bytes 0-9/36') {
      throw new Error('第一段协议不符');
    }
    const tag = first.headers.get('ETag');
    if (!tag || tag.startsWith('W/')) throw new Error('缺少强校验器');
    const a = new Uint8Array(await first.arrayBuffer());
    if (a.length !== 10) throw new Error('第一段长度不符');
    const second = await fetch('/file', {
      headers: { Range: 'bytes=10-', 'If-Range': tag }
    });
    let result;
    if (second.status === 200) {
      // 旧片段必须丢弃,不能追加完整新版本。
      result = new Uint8Array(await second.arrayBuffer());
    } else if (second.status === 206 &&
               second.headers.get('ETag') === tag &&
               second.headers.get('Content-Range') === 'bytes 10-35/36') {
      const b = new Uint8Array(await second.arrayBuffer());
      if (b.length !== 26) throw new Error('第二段长度不符');
      result = new Uint8Array(a.length + b.length);
      result.set(a); result.set(b, a.length);
    } else {
      throw new Error('续读失败:' + second.status);
    }
    out.textContent = new TextDecoder().decode(result);
  } catch (error) { out.textContent = error.message; }
  finally { button.disabled = false; }
};
</script>

这里硬编码完整长度三十六,是为了让错误一眼可见,不是通用下载器设计。真实客户端应严格解析 Content-Range,确认起点等于已保存的字节数、总长与当前任务一致、结束位置与实际接收长度匹配,再提交到持久化存储。写入成功后才更新已完成偏移,否则页面崩溃可能留下“进度在前,数据在后”的状态。恢复任务时还应保存原始资源标识、强标签和目标文件身份,不能只存一个整数。

如果第二次收到二百状态,例子直接用新响应替换结果,不尝试猜测它是否只是缺少 Content-Range 的部分响应。服务端可以合法忽略范围请求;客户端不能凭请求意图推定响应内容。若完整响应很大,则应先丢弃旧任务并建立新的流式接收,而不是在浏览器内把旧片段、新文件和合并副本同时保存。

启动与手工观察

目录只有 server.mjs、index.html 和后面的 test.mjs。先运行 node --version 确认运行环境,再执行 node server.mjs。浏览器访问 http://127.0.0.1:3000,点击按钮,预期输出数字零到九以及小写英文字母。服务端仅监听回环地址,不要为了实验方便直接暴露到公网。

可以用命令行检查实际响应头:

curl -i -H 'Range: bytes=0-9' http://127.0.0.1:3000/file
curl -i -H 'Range: bytes=-3' http://127.0.0.1:3000/file
curl -i -H 'Range: bytes=36-' http://127.0.0.1:3000/file
curl -I -H 'Range: bytes=0-9' http://127.0.0.1:3000/file
curl -i -H 'Range: bytes=10-' -H 'If-Range: "old"' http://127.0.0.1:3000/file

这些命令是供读者复现的手工观察步骤,本文没有把它们记为已执行验证。第一条应收到十字节片段,第二条收到 xyz,第三条没有响应体但包含完整长度,第四条仍是完整长度的 HEAD,第五条会返回全部三十六字节。测试时把预期写在命令旁边,比只看网络面板里一排绿色请求更容易发现偏移错误。

用真实 HTTP 请求固定行为

将以下文件保存为 test.mjs,执行 node --test test.mjs。测试不是只调用解析函数,它还真正启动回环 HTTP 服务,用 Node 内置 fetch 检查状态、响应头和返回内容。随机端口避免与手工运行服务发生冲突,测试结束关闭监听,不留下后台服务。

import test from 'node:test';
import assert from 'node:assert/strict';
import { makeServer, selectRange } from './server.mjs';
const data = Buffer.from('0123456789abcdefghijklmnopqrstuvwxyz');
test('HTTP range contract', async (t) => {
  const server = makeServer(data);
  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
  t.after(() => new Promise(resolve => server.close(resolve)));
  const url = `http://127.0.0.1:${server.address().port}/file`;
  const cases = [
    [undefined, 200, data.toString(), null],
    ['bytes=0-9', 206, '0123456789', 'bytes 0-9/36'],
    ['bytes=10-', 206, 'abcdefghijklmnopqrstuvwxyz', 'bytes 10-35/36'],
    ['bytes=-3', 206, 'xyz', 'bytes 33-35/36'],
    ['bytes=34-999', 206, 'yz', 'bytes 34-35/36'],
    ['bytes=-999', 206, data.toString(), 'bytes 0-35/36'],
    ['bytes=36-', 416, '', 'bytes */36'],
    ['bytes=-0', 416, '', 'bytes */36'],
    ['bytes=9-2', 200, data.toString(), null],
    ['bytes=0-1,4-5', 200, data.toString(), null],
    ['items=0-1', 200, data.toString(), null],
    ['bytes=9007199254740993-', 416, '', 'bytes */36']
  ];
  for (const [range, status, body, cr] of cases) {
    await t.test(String(range), async () => {
      const r = await fetch(url, { headers: range ? { Range: range } : {} });
      assert.equal(r.status, status);
      assert.equal(r.headers.get('Content-Range'), cr);
      assert.equal(await r.text(), body);
    });
  }
  await t.test('HEAD ignores Range', async () => {
    const r = await fetch(url, { method: 'HEAD', headers: { Range: 'bytes=0-1' } });
    assert.equal(r.status, 200);
    assert.equal(r.headers.get('Content-Length'), '36');
    assert.equal(await r.text(), '');
  });
  const head = await fetch(url, { method: 'HEAD' });
  const tag = head.headers.get('ETag');
  for (const [value, status] of [[tag, 206], ['"old"', 200], ['W/' + tag, 200]]) {
    await t.test('If-Range ' + value, async () => {
      const r = await fetch(url, { headers: { Range: 'bytes=0-1', 'If-Range': value } });
      assert.equal(r.status, status);
      assert.equal(await r.text(), status === 206 ? '01' : data.toString());
    });
  }
  await t.test('POST rejected', async () => {
    const r = await fetch(url, { method: 'POST' });
    assert.equal(r.status, 405); assert.equal(r.headers.get('Allow'), 'GET, HEAD');
  });
  await t.test('empty and malformed parser cases', () => {
    assert.equal(selectRange('bytes=0-', 0), false);
    assert.equal(selectRange('bytes=-1', 0), false);
    assert.equal(selectRange('bytes=-', 36), null);
    assert.equal(selectRange('bytes=' + '9'.repeat(257) + '-', 36), null);
  });
});

实际执行结果为十九项通过、零项失败。这里十九包含一个父测试和十八个子测试;子测试覆盖十二种范围输入、HEAD、三种 If-Range、方法拒绝和一组空文件及畸形输入解析断言。端到端请求使用三十六字节实体,空文件目前只检查了解析函数,没有伪称完成空文件 HTTP 全链路验证。

浏览器页面的脚本已随文提供,但没有在真实浏览器中执行点击和网络面板检查;视频播放、移动浏览器兼容、代理转发、真实网络中断以及并发压力同样未验证。Node 的 fetch 测试能够证明这套本地 HTTP 路径和断言通过,不能自动证明所有浏览器和部署拓扑都表现一致。不要把一个绿色测试汇总扩展成完整生产验收。

从内存实验迁移到磁盘文件

上线时最容易引入的回归不是 Range 正则,而是元数据与内容读到不同版本。先 stat 某路径得到长度,再按同一路径打开流,中间文件可能被替换。此时响应头描述旧长度,响应体却来自新文件。更隐蔽的是原地覆盖:即使已经打开描述符,也不能保证读取期间底层字节不变化。文件句柄解决的是路径引用问题,并不天然提供不可变快照。

更可靠的落地方式是让发布流程生成内容不可变的对象,以版本标识或内容哈希命名,再把业务文件名指向最新版本。请求开始时选定一个版本,授权、大小、媒体类型、强标签以及读取区间全部绑定这个版本。不要在同一次响应里重新查一次“最新版本”。旧版本的清理还应尊重正在服务的请求和允许恢复的时间窗口。

如果改用 filehandle.createReadStream,Node 文档规定 start 和 end 都包含边界,不能把 Buffer.subarray 的排他结束位置原样移植过去。本文缓冲区切片使用 end 加一,而文件流使用区间原始 end。文件流还需要处理客户端断开、文件读取错误以及关闭句柄;响应头发送后再发生磁盘错误时,通常只能终止连接,不能补发一个完整的 JSON 错误响应。Node.js:FileHandle.createReadStream

背压和并发限制也要分别设计。流式读取降低单请求整文件驻留内存,却不限制同时打开多少文件、占用多少网络连接。本文 res.end 直接发送小快照,没有演示生产文件流的背压控制,也没有慢客户端容量测量。每请求限速、并发预算、文件描述符上限和超时策略应按实际负载确定,不能从三十六字节测试推导吞吐承诺。

部署边界:压缩、权限与播放器

字节偏移针对选定表示。若应用按未压缩内容计算偏移,代理却临时把返回体压缩,客户端看到的内容编码和偏移契约就可能不一致。本例不压缩并设置 no-transform;真正上线还必须检查反向代理和 CDN 的相关配置,并验证它们是否保持 Content-Range、Content-Length 和实体标签一致。请求经过几层代理不是问题,几层对同一表示作了不同假设才是问题。

Range 不绕过鉴权。私有文件的 HEAD、完整 GET 和部分 GET 都应该走同一套权限校验,不能为了快速返回长度先泄露文件是否存在。客户端传来的文件名也不能直接拼成磁盘路径。本例只有固定路由,故意没有提供任意路径读取功能;扩展成文件服务时要先把授权的业务 ID 映射为受控对象,再选择读取区间。

视频拖动还依赖容器结构、索引位置和编码支持。把本例的二进制类型改成 video/mp4,再塞一个文件,并不能证明播放器能够快速定位到任意时间。播放器自己决定请求哪些字节,服务端应正确回答;准备适合随机读取的媒体文件属于另一项工作。上线前应使用真实媒体、目标浏览器与完整代理链,观察拖动时的请求序列,而不是只检查是否出现过二百零六。

最后,支持单区间是一个可以清楚说明的能力边界。暂不支持多区间时返回完整内容通常容易保持兼容,但也可能增加流量。若业务确实依赖多区间,再实现对应媒体类型、边界与滥用防护,并新增覆盖重叠范围、无序范围和超量范围的测试。不要为了一个演示请求看起来先进,提前增加无法验证的协议分支。

这套实验的验收标准很具体:同版本的两个区间能够恢复原始字节,版本不匹配时放弃旧片段,范围无交集时得到明确失败,服务器选择完整响应时不发生重复追加。把这四件事固定下来,续读功能才有可靠的起点。

相关文章

评论

登录后即可参与讨论

暂无评论。