Axios Node.js 带宽限速实战：maxRate 双向速率控制与流式节流原理

本篇技术指南聚焦 Axios 在 Node.js 环境下提供的带宽限速能力（maxRate 配置项），讲解如何对上传、下载或双向流量分别设置字节/秒级别的速率上限，并结合进度回调实时观测实际传输速率。读完本文，你将掌握 maxRate 的完整取值形式与实战配置方法，并能从源码层面理解 Axios 如何用时间窗口 + 分块切片的流式节流算法（AxiosTransformStream）实现真正的带宽封顶。

为什么需要带宽限速

在大批量数据搬运、后台定时任务或"礼貌型"爬虫（polite scraping）场景中，HTTP 请求如果以连接允许的最高速度传输，很容易打满带宽、挤占其他业务流量，或对目标服务器造成压力。Axios 通过 Node.js 的 HTTP 适配器（http adapter）提供 maxRate 选项，让你可以直接在请求配置中控制上传或下载的数据速率。

一个重要的适用边界：maxRate 仅对 Node.js 的 HTTP 适配器生效，在浏览器环境中不起作用。浏览器侧的传输由 XHR/Fetch 接管，没有可插入的流式节流位置。

maxRate 的取值形式

maxRate 接受两种形式：

1. 单个数字：单位为字节/秒（bytes per second），同一个限速值同时应用于上传和下载两个方向；
2. 数组：第一个元素是上传限速，第二个元素是下载限速。
   • 写 [uploadRate]（只写第一项）时，只限制上传；
   • 写 [uploadRate, downloadRate] 时，两个方向同时生效；
   • 第二项写 Infinity 表示"下载方向不限速"。

两种最基础的用法示例（继承自官方文档）：

// 上传和下载都限制为 100 KB/s
await axios.get(URL, { maxRate: 100 * 1024 });

// 上传限制 100 KB/s，下载限制 500 KB/s
await axios.get(URL, { maxRate: [100 * 1024, 500 * 1024] });

这种"数字或二元组"的取值约定在 TypeScript 类型定义中有明确体现，见 index.d.ts：

type MaxUploadRate = number;
type MaxDownloadRate = number;

// AxiosRequestConfig 中
maxRate?: number | [MaxUploadRate, MaxDownloadRate];

在 HTTP 适配器内部，两种形式会被统一拆解为 maxUploadRate 与 maxDownloadRate 两个内部变量，见 lib/adapters/http.js 第 847–852 行：

if (utils.isArray(maxRate)) {
  maxUploadRate = maxRate[0];
  maxDownloadRate = maxRate[1];
} else {
  maxUploadRate = maxDownloadRate = maxRate;
}

从这段源码可以印证文档的语义：传入单个数字时，两个方向被赋予相同上限；传入数组时，缺失的位置保持 undefined（即不限速），后续经过 utils.toFiniteNumber 归一化为 0，而 maxRate: 0 在节流流中表示"不启用限速"。

另外，maxRate 与普通配置一样支持实例级/请求级合并。仓库中的冒烟测试 tests/smoke/esm/tests/rateLimit.smoke.test.js 验证了这一点：axios.create({ maxRate: [1000, 2000] }) 创建的实例，若具体请求再传 maxRate: [3000, 4000]，最终生效的是请求级的 [3000, 4000]。

上传限速：边限速边观测速率

上传场景中，可以限制发送速度的同时，通过 onUploadProgress 回调拿到实时进度与实际速率：

const { data } = await axios.post(SERVER_URL, myBuffer, {
  onUploadProgress: ({ progress, rate }) => {
    const percent = (progress * 100).toFixed(1);
    const kbps = (rate / 1024).toFixed(1);
    console.log(`Upload [${percent}%] at ${kbps} KB/s`);
  },

  maxRate: [100 * 1024], // 上传封顶 100 KB/s
});

进度回调的数据结构值得展开。Axios 在 lib/helpers/progressEventReducer.js 中构造传给回调的对象，除 progress（0–1 的进度比例）与 rate（当前速率，字节/秒）外，还包括：

• loaded / total：已传输字节数与总字节数（total 依赖 Content-Length）；
• bytes：本次回调区间内新增的字节数；
• estimated：按当前速率估算的剩余时间（秒），当速率与总长都已知时给出；
• lengthComputable：总长度是否可计算；
• upload: true 或 download: true：标记回调方向。

其中 rate 字段由 lib/helpers/speedometer.js 中的"速率计"算法计算：它维护一个固定容量的环形缓冲区（默认 10 个采样点），每次写入当前块的字节数与时间戳，当首个采样点距当前时间超过最小窗口（默认 1000ms）后，用窗口内累计字节数除以经过时间并四舍五入，得到平滑后的字节/秒速率。这解释了为什么进度回调中打印出的速率是"滑动窗口均值"而非瞬时值，读数会更稳定、更适合展示。

下载限速：控制大响应体的接收速度

对大文件的 GET 下载，同样可以限制接收速率：

const { data } = await axios.get(FILE_URL, {
  onDownloadProgress: ({ progress, rate }) => {
    const percent = (progress * 100).toFixed(1);
    const kbps = (rate / 1024).toFixed(1);
    console.log(`Download [${percent}%] at ${kbps} KB/s`);
  },

  maxRate: [Infinity, 200 * 1024], // 上传不限速，下载限制 200 KB/s
  responseType: "arraybuffer",
});

注意示例中 maxRate 第一项传了 Infinity：按 HTTP 适配器的解析逻辑，这表示上传方向不设上限（Infinity 经 toFiniteNumber 归一化为 0，即不限速），下载方向封顶 200 KB/s。responseType: "arraybuffer" 用于把限速后的完整响应体收集为二进制返回；若需要流式处理响应（例如边下边写磁盘），保持默认的 stream 类型即可，节流逻辑不受影响。

同时限制上传与下载

把两个方向的限速值放进数组，即可在单个请求中同时控制收发：

await axios.post(SERVER_URL, largeBuffer, {
  maxRate: [50 * 1024, 500 * 1024], // 上传 50 KB/s，下载 500 KB/s
});

这个模式适合"上传大文件并接收大响应"的对称场景，例如对象存储的上传接口返回大体积处理结果。

源码级实现：AxiosTransformStream 的时间窗口节流

maxRate 的实际执行落在 Node.js HTTP 适配器的两条流式管线上。上传侧（lib/adapters/http.js 第 854–880 行）：

if (data && (onUploadProgress || maxUploadRate)) {
  if (!utils.isStream(data)) {
    data = stream.Readable.from(data, { objectMode: false });
  }

  data = stream.pipeline(
    [
      data,
      new AxiosTransformStream({
        maxRate: utils.toFiniteNumber(maxUploadRate),
      }),
    ],
    utils.noop
  );
  // ... 之后才绑定 onUploadProgress 的 'progress' 事件监听
}

下载侧（同文件第 1125–1147 行）则在收到响应后把 AxiosTransformStream 挂进响应流数组，再经过解压管线（zlib.createUnzip 等）交给后续处理。两条管线说明了一个关键事实：只要配置了 maxRate，即便你不关心进度，Axios 也会插入节流流；而进度回调的数据正是节流流每 push 一个块时发出的 progress 事件（见 lib/helpers/AxiosTransformStream.js 中的 internals.isCaptured && this.emit('progress', internals.bytesSeen)）。

节流流的核心参数

AxiosTransformStream 构造函数中的默认参数（lib/helpers/AxiosTransformStream.js 第 10–24 行）揭示了节流的粒度：

参数	默认值	含义
maxRate	0	速率上限（字节/秒），0 表示不限速
chunkSize	64 * 1024	可读流高水位标记，也作为单次最大切片基准
minChunkSize	100	切片后"余量"小于此值则不再拆分，避免过度碎片化
timeWindow	500	速率控制的时间窗口（毫秒）
ticksRate / samplesCount	2 / 15	供速率采样使用的参数

时间窗口算法如何工作

_transform 方法（第 62–153 行）实现了基于固定时间窗口的限速逻辑，核心步骤：

1. 换算窗口配额：divider = 1000 / timeWindow，bytesThreshold = maxRate / divider。以 maxRate = 100 * 1024（100 KB/s）、timeWindow = 500ms 为例，每个窗口允许通过 100*1024/2 = 51200 字节；
2. 窗口记账：当距上次窗口起点（internals.ts）达到 timeWindow 时，重置 bytesLeft 为本窗口剩余配额；
3. 超窗等待：如果本窗口配额已用完（bytesLeft <= 0），用 setTimeout(..., timeWindow - passed) 把剩余数据延迟到下一个窗口再处理——这就是"封顶"的实际手段，数据不会被丢弃，只是被时间推迟；
4. 分块拆分：若当前块大小超过 bytesLeft（且超出部分大于 minChunkSize），先推出去 maxChunkSize 大小的前缀，余量通过 transformChunk 递归处理，从而把大块数据摊平到多个时间窗口内；
5. 背压保护：pushChunk 在下游背压时（this.push 返回 false）挂起回调到 onReadCallback，等待流恢复读取。

这套"配额 + 延迟 + 拆分"的组合意味着：实际速率不会明显超过 maxRate，但会以 timeWindow（500ms）为粒度出现轻微的阶梯式波动——这是流式节流的固有特性，从源码结构看属于有意的工程折中（避免引入 token bucket 的额外复杂度）。

进度事件如何被消费

节流流发出的 progress 事件在 HTTP 适配器中经过三层包装后成为你在回调里看到的对象：

1. progressEventDecorator：把节流流的 loaded 字节数包装为 { lengthComputable, total, loaded }；
2. progressEventReducer：用 speedometer 计算 rate，组装 progress/bytes/estimated 等字段，并用 throttle 按 freq = 3（毫秒）节流，防止高频小数据块触发过密回调；
3. asyncDecorator：把回调调度到微任务，保证你的处理函数不阻塞流管线。

单元测试 tests/unit/adapters/http.test.js 中也有直接对 maxRate: [0, configRate] 等组合的断言（第 5146、5198 行附近），配合冒烟测试 tests/smoke/cjs/tests/rateLimit.smoke.test.cjs 与 tests/smoke/esm/tests/rateLimit.smoke.test.js，覆盖了数字/元组两种形态的透传、实例与请求级配置合并、以及 Node 传输流程下端到端不报错。

使用建议与注意事项

• 单位是字节/秒：100 * 1024 表示 100 KB/s，不要误写成 100 表示 100 KB/s；
• 仅 Node.js HTTP 适配器生效：浏览器端（xhr/fetch 适配器）传 maxRate 会被忽略，配置不会报错，但也不会限速；
• [Infinity, rate] 是"只限下载"的惯用写法：第一位置 Infinity 经归一化后等价于不限速；
• 进度与限速共用一条管线：一旦设置 maxRate（或进度回调），请求/响应体都会经过 AxiosTransformStream，流式背压（backpressure）由该流统一处理，高并发大批量任务下可放心使用；
• 限速精度与 timeWindow 相关：默认 500ms 窗口意味着速率是"每 500ms 检查一次配额"，短时突发不会精确到毫秒级，但对带宽封顶目标足够。

小结

maxRate 是 Axios 面向 Node.js 场景的带宽治理开关：单个数字对收发同限，元组对收发分限，配合 onUploadProgress / onDownloadProgress 还能拿到带滑动窗口速率（rate）的进度事件。底层由 AxiosTransformStream 以 500ms 时间窗口的配额、setTimeout 延迟与分块拆分实现真正的流式封顶，源码位于 lib/helpers/AxiosTransformStream.js，接入点在 lib/adapters/http.js 的上传与下载两条管线中。对于后台批量任务与需要克制带宽占用的抓取场景，这是一套开箱即用、无需外挂限速库的完整方案。