用 HTTP Range 实现大文件断点续传接口

举报
yd_229231784 发表于 2026/11/15 17:05:55 2026/11/15
【摘要】 用 Express 实现大文件断点续传下载接口:解析单段 Range 返回 206 与 Content-Range,越界时返回 416 和 bytes */总长度,并用强 ETag 配合 If-Range 避免文件变更后分段拼接错乱,附 curl 验证步骤。

用 HTTP Range 做断点续传:206、416 与 If-Range

问题场景

大文件下载中断后,如果每次从 0 开始,既浪费带宽,也无法保证分段拼接正确。HTTP Range 允许客户端只请求文件的一段,服务端用 206 Partial Content 和 Content-Range 告知实际范围;请求越界时返回 416 Range Not Satisfiable,并在 Content-Range 中使用 bytes */总长度。当文件可能变化时,客户端会带 If-Range(通常是强 ETag);服务端若发现 ETag 不匹配,应忽略 Range 返回完整 200,避免旧分段和新文件拼在一起。

Express 最小实现

依赖 express,示例文件为同目录 big.bin:

const express = require('express');
const fs = require('fs');
const path = require('path');
const { pipeline } = require('stream');

const app = express();
const FILE = path.join(__dirname, 'big.bin');
const QUOTE = String.fromCharCode(34);

function makeEtag(st) {
  return QUOTE + st.size.toString(16) + '-' + Math.floor(st.mtimeMs).toString(16) + QUOTE;
}

function parseRange(header, size) {
  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim());
  if (!m) return { kind: 'unsupported' };
  const a = m[1];
  const b = m[2];
  if (a === '' && b === '') return { kind: 'unsupported' };
  if (size === 0) return { kind: 'unsat' };
  let start;
  let end;
  if (a === '') {
    const suffix = Number(b);
    if (!Number.isSafeInteger(suffix) || suffix <= 0) return { kind: 'unsat' };
    start = Math.max(size - suffix, 0);
    end = size - 1;
  } else {
    start = Number(a);
    end = b === '' ? size - 1 : Number(b);
    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)) {
      return { kind: 'unsupported' };
    }
    if (start > end) return { kind: 'unsat' };
  }
  if (start >= size) return { kind: 'unsat' };
  if (end >= size) end = size - 1;
  return { kind: 'ok', start, end };
}

function sendFull(req, res, size) {
  res.set('Content-Length', String(size));
  if (req.method === 'HEAD' || size === 0) return res.end();
  return pipeline(fs.createReadStream(FILE), res, (err) => {
    if (err) res.destroy(err);
  });
}

app.get('/download', async (req, res) => {
  let st;
  try {
    st = await fs.promises.stat(FILE);
  } catch {
    return res.status(404).end();
  }

  const etag = makeEtag(st);
  res.set('Accept-Ranges', 'bytes');
  res.set('ETag', etag);
  res.set('Content-Type', 'application/octet-stream');

  const range = req.headers.range;
  const ifRange = req.headers['if-range'];

  if (range && ifRange && ifRange !== etag) {
    return sendFull(req, res, st.size);
  }
  if (!range) {
    return sendFull(req, res, st.size);
  }

  const part = parseRange(range, st.size);
  if (part.kind === 'unsupported') {
    return sendFull(req, res, st.size);
  }
  if (part.kind === 'unsat') {
    res.status(416);
    res.set('Content-Range', `bytes */${st.size}`);
    return res.end();
  }

  const { start, end } = part;
  res.status(206);
  res.set('Content-Range', `bytes ${start}-${end}/${st.size}`);
  res.set('Content-Length', String(end - start + 1));
  if (req.method === 'HEAD') return res.end();

  return pipeline(fs.createReadStream(FILE, { start, end }), res, (err) => {
    if (err) res.destroy(err);
  });
});

app.listen(3000, () => {
  console.log('GET http://127.0.0.1:3000/download');
});

运行:

node -e "require('fs').writeFileSync('big.bin', Buffer.alloc(1024 * 1024))"
npm i express
node app.js

服务监听 http://127.0.0.1:3000/download。parseRange 只接受单段 bytes=start-end、bytes=start-、bytes=-suffix;多段或语法不支持时回退完整 200,越界才 416。sendFull 同时处理 HEAD 和 0 字节文件。

curl 分段验证

另开终端,先取前 512 KiB,再取剩余部分并拼接:

curl -sS -D - -o p1 -H 'Range: bytes=0-524287' http://127.0.0.1:3000/download
# 期望 206,Content-Range: bytes 0-524287/1048576,Content-Length: 524288

curl -sS -D - -o p2 -H 'Range: bytes=524288-' http://127.0.0.1:3000/download
cat p1 p2 > joined.bin
cmp big.bin joined.bin && echo OK

越界请求应返回 416:

curl -sS -D - -o /dev/null -H 'Range: bytes=2000000-' http://127.0.0.1:3000/download
# 期望 416,Content-Range: bytes */1048576

验证 If-Range:先从正常响应头复制 ETag(包含双引号),替换下面的占位值:

curl -sS -D - -o p3 -H 'Range: bytes=0-1023' -H 'If-Range: "100000-18f..."' http://127.0.0.1:3000/download
# 匹配时 206

curl -sS -D - -o full.bin -H 'Range: bytes=0-1023' -H 'If-Range: "stale"' http://127.0.0.1:3000/download
wc -c full.bin   # 期望 1048576,状态 200

边界与限制

  • 只实现单段 Range。多段请求按不支持处理并回退 200;如需 multipart/byteranges 要另行实现。
  • If-Range 只做强 ETag 精确比较;日期形式按不匹配处理,回退完整 200,安全但可能多传。ETag 由文件大小和 mtime 生成,若内容变化但 mtime 未变会误判,生产可改用内容哈希或版本号。
  • 416 的 Content-Range 必须是 bytes */总长度;206 的 Content-Range 必须与 Content-Length、实际读取的 start/end 一致。
  • 文件需支持随机读。对象存储场景应把 Range 转发给后端,不要先完整下载到本地;同时注意反向代理超时和客户端重试。
  • 并发写入同一文件可能读到不一致内容,建议固定文件句柄或使用版本化对象。
【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。