# @cloudflare/speedtest 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/speedtest/

版本：1\.17\.0
npm 元数据更新时间：2026-11-09T14:55:18.909Z
中文译文更新时间：2026-11-10T03:03:40.087Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/speedtest
原文对照：https://npmcn.com/package/%40cloudflare/speedtest/?lang=original
项目主页：https://github.com/cloudflare/speedtest
源码仓库：https://github.com/cloudflare/speedtest

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：305 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2023-02-02T18:01:14.323Z
- 最新版本发布：2026-11-09T14:55:18.411Z
- 近 30 天下载量：358293（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 20 个）

## 中文简介

对 Cloudflare 的边缘网络进行网络速度测试的组件

## 安装

```sh
npm install @cloudflare/speedtest
```

也可以使用：`pnpm add @cloudflare/speedtest`、`yarn add @cloudflare/speedtest`、`bun add @cloudflare/speedtest`

## README

# 云浮速度测试

[![NPM package](https://img.shields.io/npm/v/@cloudflare/speedtest)](https://npmjs.org/package/@cloudflare/speedtest) [![Build Size](https://img.shields.io/bundlephobia/minzip/@cloudflare/speedtest)](https://bundlephobia.com/result?p=@cloudflare/speedtest) [![NPM Downloads](https://img.shields.io/npm/dt/@cloudflare/speedtest)](https://www.npmtrends.com/@cloudflare/speedtest)

`@cloudflare/speedtest` 是一个用于测量客户端互联网连接质量的 JavaScript 模块。 使用Cloudflare 速度测试测量应用程序的测量引擎 [https://speed.cloudflare.com (中文(中国大陆) )](https://speed.cloudflare.com/)。 。 。 .

模块针对 [云雾花](https://www.cloudflare.com/) 边缘网络并依赖 [性能资源Timing 浏览器 api](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming) 以获取计时结果. 网络连接的特点是有下载/上载带宽、延迟和包丢失等项目.

请注意,Cloudflare在完成后收集测量结果,以便计算关于互联网连接质量的综合见解.

## 安装

将此软件包添加到您的 `package.json` 在您的项目目录根中运行此选项 :

```sh
npm install @cloudflare/speedtest
```

## 简单使用

```js
import SpeedTest from '@cloudflare/speedtest';

new SpeedTest().onFinish = results => console.log(results.getSummary());
```

## API 参考

`SpeedTest` 是一个 JavaScript 类,应该与 `new` 关键词 不需要通过一个配置对象,因为所有项目都有默认值.

### 证据

```js
new SpeedTest({ configOptions })
```

标有QQ的选项是 **实验和不稳定**:它们可能改变行为, 重新命名,或在任何发布中被删除,包括补丁。 不依赖 他们.

| 配置选项 | 说明 | 默认 |
| --- | --- | --- |
| **自动启动**数字 : _布尔_ | 是否在即时状态下自动启动测量 . | `true` |
| **计量 目标**数字 : _字符串 \[\]_ | 发送延迟、下载和上传请求的源头 `measurementDownloadPath` 财务报告和审定财务报表 `measurementUploadPath`测试在目标上空延后 当空地, `downloadApiUrl` 财务报告和审定财务报表 `uploadApiUrl` 改为使用。 一个不裸露的入口 `http(s)` 来源抛出 a `TypeError` 当引擎被创建时。 与页面不同来源的目标必须发出 `Timing-Allow-Origin` 页: 对目标的请求未经报告即通过 `onError` 然后跳过. | `[]` |
| **下行负荷平面**数字 : _字符串_ | 每集的延迟和下载请求路径 `measurementTargets`。它可能包括一个查询字符串。 一条没有开始的道路 `/` 丢出一个 `TypeError` 当引擎被创建时. | `/__down` |
| **度量加载Path**数字 : _字符串_ | 每个上传请求的路径 `measurementTargets`。它可能包括一个查询字符串。 一条没有开始的道路 `/` 丢出一个 `TypeError` 当引擎被创建时. | `/__up` |
| **下载 ApiUrl**数字 : _字符串_ | _折旧:使用 `measurementTargets`。 。 。 ._ 用于执行下载的 API URL 获取请求, 当 `measurementTargets` 为空. | `https://speed.cloudflare.com/__down` |
| **上传 ApiUrl**数字 : _字符串_ | _折旧:使用 `measurementTargets`。 。 。 ._ 用于执行上传 POST 请求的 API URL, 当 `measurementTargets` 为空. | `https://speed.cloudflare.com/__up` |
| **转动ServerUri**数字 : _字符串_ | TURN服务器的URI用来测量包丢失,例如. `turn.cloudflare.com:3478`。见 [数据包损失](https://npmcn.com/package/%40cloudflare/speedtest/#readme-packetloss)。 。 。 . | `null` |
| **转动服务器CredsApiUrl**数字 : _字符串_ | 返回 TURN 服务器证书的 URI 。 期待 JSON 对 `username` 财务报告和审定财务报表 `credential` 键。 见 [数据包损失](https://npmcn.com/package/%40cloudflare/speedtest/#readme-packetloss)。 。 。 . | `null` |
| **转向服务器用户**数字 : _字符串_ | TURN 服务器证书的用户名 . | \- 说吧 |
| **转向服务器Pass**数字 : _字符串_ | TURN服务器证书的密码. | \- 说吧 |
| **权限键**数字 : _字符串_ | 🧪 _实验._ 将测试结果归咎于注册客户的不透明标志,作为 `Authorization: Bearer` 关于测量、TURN证书和成果记录请求的页眉。 从你自己的后端获取——引擎从不要求自己一个. 要求数 `authorizationEnabled`他自己是不会被派遣的。 除非 `allowInsecureAuthorizationToken` 已经设定. | `null` |
| **授权已启用**数字 : _`'header'` 布尔_ | 🧪 _实验._ 选择发送 `authorizationToken`,否则即使在设定时也不予考虑. `'header'` 财务报告和审定财务报表 `true` 都发作 `Authorization: Bearer`· ; `true` 是永久别名,用于: `'header'`,因此可以添加未来的传输,而不改变一个已有的配置的作用. | `undefined` |
| **允许不安全认证**数字 : _布尔_ | 🧪 _实验._ 发送 `authorizationToken` 即使终点不是HTTPS, 用于本地开发对一个 `http://` 服务器。 在制作中永远不要启用此功能: 服务器将一个从平白文字上看到的符号视为已损坏并撤销它 . | `false` |
| **测量**数字 : _数组_ | 由速度测试引擎执行的测量序列. 见 [下级](https://npmcn.com/package/%40cloudflare/speedtest/#readme-measurement-config) 用于此选项的特定语法. |  |
| **下行记录**数字 : _布尔_ | 是否与下载请求同时进行额外的延迟测量,以测量加载的延迟(下载期间). | `true` |
| **升入负载**数字 : _布尔_ | 是否与上传请求同时进行额外的延迟测量,以测量加载的延迟(在上传期间). | `true` |
| **装入温度**数字 : _编号_ | 在装入的延迟请求之间等待的时间间隔( 毫秒) . | 400个 |
| **带宽**数字 : _编号_ | 在下载/上载计量套件中达到的最小持续时间(以毫秒计),用于在相同方向上停止文件尺寸较大的进一步测量. | 1 000个 |
| **中止请求期限**数字 : _编号_ | 单个请求的最长期限(以毫秒为单位). 需要更长时间的请求被中止和跳过 . `bandwidthAbortRequestDuration` 是一个被贬值的别名. | 0 (残疾) |
| **中止测试期限**数字 : _编号_ | 整个测试的最大运行时间(以毫秒计,不包括暂停时间). 到达后,测试以迄今所收集的结果为结束. | 0 (残疾) |
| **估计服务时间**数字 : _编号_ | 如果下载/上载API不返回 a `server-timing` 包含在服务器所花时间的响应头,这个固定值(以毫秒计)将从所有时间到第一字节的计算中减去. | 0 个 |
| **死亡率**数字 : _编号_ | 百分位数( 0到 1 之间) 用于从一组测量中计算耐久性 . | 0.5 (韩语) |
| **带宽百分点**数字 : _编号_ | 从一组测量中计算带宽的百分位数( 0到 1 之间) . | 0.9 (中文(简体) ) |
| **带宽最小请求期限**数字 : _编号_ | 要求考虑在带宽计算中使用足够好的测量方法的最小持续时间(以毫秒计). | 10个 |
| **装入请求结束**数字 : _编号_ | 要求考虑装入连接的最小期限(以毫秒计). | 250号 |
| **装入LatencyMax点**数字 : _编号_ | 为加载的耐久测量保留的最大数据点数. 超过这一数额时,保留最新数额. | 20国 |

### 属性

| 属性 | 说明 |
| --- | --- |
| **结果**数字 : _[结果](https://npmcn.com/package/%40cloudflare/speedtest/#readme-results-object)_ | 获取电流 [测试结果](https://npmcn.com/package/%40cloudflare/speedtest/#readme-results-object) 对象。 如果测试仍在运行, 则可能得出不完整的值 . |
| **正在运行**数字 : _布尔_ | 获取测试引擎是否正在运行 . |
| **已完成**数字 : _布尔_ | 更清楚地了解测试引擎是否完成了所有测量,结果被认为是最终的. |

### 方法

| 方法 | 说明 |
| --- | --- |
| **播放()** | 开始或恢复测量。 如果引擎已经运行或已完成, 则不做任何事 . |
| **暂停( c)** | 暂停测量。 如果引擎已经暂停或完成, 则不做任何工作 . |
| **重新启动( c)** | 清除当前结果并重新开始测量. |

### 通知事件

| 事件方法 | 参数 | 说明 |
| --- | --- | --- |
| **运行变化** | 运行中 : _布尔_ | 每当测试引擎启动或停止时,就发出警报. 当前状态作为函数参数包含. |
| **关于结果的变化** | {类型 : _字符串_ {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 | 任何项目在结果发生变化时都会被援引,通常表示测量完成. 改变的计量类型作为信息属性被包括在函数参数中. |
| **完成时** | 结果 : _[结果](https://npmcn.com/package/%40cloudflare/speedtest/#readme-results-object)_ | 当测试结束时,用 [结果对象](https://npmcn.com/package/%40cloudflare/speedtest/#readme-results-object) 以函数参数方式收集 . |
| **错误** | 错误 : _字符串_状态 : _数字 qq 未定义_ | 当在一次测量中发生出错时即告发,可用时为HTTP状态. 多数错误不会停止测试;呼叫 `pause()` 从这个召回停止它. |

### 测量配置

试验发动机将进行的具体测量(及其序列)可使用 `measurements` 配置选项 。 这应该是一系列物体,每个物体都有 `type` 字段,加上该计量类型特有的额外字段.

由引擎执行的默认测量数据集是:

```js
[
  { type: 'latency', numPackets: 1 }, // initial latency estimation
  { type: 'download', bytes: 1e5, count: 1, bypassMinDuration: true }, // initial download estimation
  { type: 'latency', numPackets: 20 },
  { type: 'download', bytes: 1e5, count: 9 },
  { type: 'download', bytes: 1e6, count: 8 },
  { type: 'upload', bytes: 1e5, count: 8 },
  { type: 'upload', bytes: 1e6, count: 6 },
  { type: 'download', bytes: 1e7, count: 6 },
  { type: 'upload', bytes: 1e7, count: 4 },
  { type: 'download', bytes: 2.5e7, count: 4 },
  { type: 'upload', bytes: 2.5e7, count: 4 },
  { type: 'download', bytes: 1e8, count: 3 },
  { type: 'upload', bytes: 5e7, count: 3 },
  { type: 'download', bytes: 2.5e8, count: 2 }
]
```

以下是每个测量类型的可用字段:

#### 延迟

| 外地 | 需求 | 说明 | 默认 |
| --- | --- | --- | :-: |
| **数字包**数字 : _编号_ | 对 | 延迟的次数得到执行请求. 这些请求是针对下载API的 `bytes=0`,然后是往返时间到第一个字节的时间 `requestStart` 财务报告和审定财务报表 `responseStart` 被提取出来. | \- 说吧 |

#### 下载/上传

每一个这些计量集都与特定的文件大小相接. 发动机遵循了每个方向(下载或上传)的坡道方法. 当一个方向有多个测量组(文件大小增加)时,引擎会继续运行,直到达到指定条件 `bandwidthFinishRequestDuration`,此时将忽略进一步朝同一方向设置.

| 外地 | 需求 | 说明 | 默认 |
| --- | --- | --- | :-: |
| **字节**数字 : _编号_ | 对 | 从下载的 API 请求的文件大小, 或张贴到上传的 API 。 每个请求的带宽(计算为每秒比特,或bps)通过除以 `transferSize` (以位数计)由请求持续时间(不包括服务器处理时间). 持续时间从浏览器报告的最后答复信头中计量(`finalResponseHeadersStart`),因此临时 `1xx` 答复并不缩短. | \- 说吧 |
| **计数**数字 : _编号_ | 对 | 执行此文件大小的请求数量 。 报告持续时间为零或负数或没有资源时段输入的请求,没有可测量的带宽:它仍然用于 `count`,但通过控制台警告从结果中丢弃,所以一个集可以返回的数据点比要求的要少。 如果在一个计量组内连续三次请求没有资源时间输入,测试以迄今收集的结果结束,并报告通过 `onError`。 。 。 . | \- 说吧 |
| **绕行定义**数字 : _布尔_ | 没有 | 是否为 `bandwidthFinishRequestDuration` 检查应当被忽略,并指示引擎在任何情况下继续测量这个方向. | `false` |

#### 数据包损失

通过向WebRTC TURN服务器提交一组UDP数据包,以及确定有多少数据包没有到达,来测量包的损失。 提交这些包可以采用分批方式,其中分批之间有睡眠时间.

包丢失是选入的:它不是默认测量的一部分,它需要你自己的TURN服务器配置. 为了启用它,增加一个 `packetLoss` 测量,以及:

-   设定 `turnServerCredsApiUrl` 返回 TURN 证书的结束点,加 `turnServerUri` (例如:. `turn.cloudflare.com:3478`),除非终点也返回 a `server` 字段,或
-   设定 `turnServerUri` 与你自己的 `turnServerUser` 财务报告和审定财务报表 `turnServerPass`。 。 。 .

```js
new SpeedTest({
  turnServerUri: 'turn.cloudflare.com:3478',
  turnServerCredsApiUrl: 'https://turn.example.com/turn-credentials',
  measurements: [
    // ...
    { type: 'packetLoss', numPackets: 1e3, responsesWaitTime: 3000 }
  ]
});
```

A 类 `packetLoss` 无任一选项的测量因出错而失败,引擎会继续到下一个测量.

使用 Cloudflare Worker 提供 TURN 证书的示例代码 [Cloudflare 实时 TURN 服务器](https://developers.cloudflare.com/realtime/turn/),可在 [实例/回合-工作者](https://npmcn.com/package/%40cloudflare/speedtest/example/turn-worker). 参考工人的 [文档](https://npmcn.com/package/%40cloudflare/speedtest/example/turn-worker/README.md) 用于设置和部署指令.

| 外地 | 需求 | 说明 | 默认 |
| --- | --- | --- | :-: |
| **数字包**数字 : _编号_ | 没有 | 要发送的 UDP 包总数 . | 100个 |
| **回复等待时间**数字 : _编号_ | 没有 | 等待最新数据包接收的时间间隔(以毫秒计),然后确定测量是否完整,所有未返回数据包是否丢失. | 5000块 |
| **批量大小**数字 : _编号_ | 没有 | 一批包的数量 。 如果该值高于 `numPackets` 只有一批货. | 10个 |
| **批次等待时间**数字 : _编号_ | 没有 | 在批次之间等待多长时间(以毫秒计). | 10个 |
| **连接 超时**数字 : _编号_ | 没有 | 连接到 TURN 服务器的超时 . | 5000块 |

### 结果对象

用于获取速度测试测量结果的一个实例对象. 此对象有以下方法:

| 方法 | 说明 |
| --- | --- |
| **获取摘要 ()** | 返回一个高层次的汇总对象,其中包含所进行测量的计算结果. |
| **获取未装入的Latency ()** | 返回闲置时连接延迟的减少值。 需要至少一个 `latency` 计量. |
| **正在获取已卸载的 Jitter ()** | 返回闲置时的连接焦点 。 慢跑被计算为相接相接的耐久度测量之间的平均距离. 至少需要两个 `latency` 测量. |
| **获取已卸载的灯塔( )** | 返回带有闲置时所测量的所有后缀的数组 。 包括按顺序衡量的一个值. |
| **获得下行记录( C)** | 在下载方向上加载时返回连接延迟的减少值。 要求数 `measureDownloadLoadedLatency` 启用. |
| **获取“ 向下下载” Jitter ()** | 在下载方向上加载时返回连接焦点 。 要求数 `measureDownloadLoadedLatency` ,以及至少两个装入的耐用度测量. |
| **获得下行LadedLatencyPoints ()** | 返回包含在下载方向上加载时所测量的所有后缀的数组 。 包括每个装入量按顺序排列的一个值. 要求数 `measureDownloadLoadedLatency` 启用. |
| **获取LadedLatency ()** | 在上传方向上加载时返回连接延迟的减少值。 要求数 `measureUploadLoadedLatency` 启用. |
| **获取 LadedJitter ()** | 在上传方向上加载时返回连接焦点 。 要求数 `measureUploadLoadedLatency` ,以及至少两个装入的耐用度测量. |
| **获取LadedLatencyPoints ()** | 返回带有在上传方向上加载时所测量的所有后缀的数组 。 包括每个装入量按顺序排列的一个值. 要求数 `measureUploadLoadedLatency` 启用. |
| **获得下载 Bandwidth ()** | 返回下载带宽的减少值(bps)。 需要至少一个 `download` 测量,比 `bandwidthMinRequestDuration` 阈值. |
| **获得下载 Bandwidth Points ()** | 返回带有所有下载测量结果的数组。 每个项目将包括以下领域: `{ bytes, bps, duration, ping, measTime, serverTime, transferSize }`。 。 。 . |
| **获取上载 Bandwidth ()** | 返回上传带宽的减少值(bps)。 需要至少一个 `upload` 测量,比 `bandwidthMinRequestDuration` 阈值. |
| **获取上载 Bandwidth Points ()** | 返回带有所有上传测量结果的数组。 每个项目将包括以下领域: `{ bytes, bps, duration, ping, measTime, serverTime, transferSize }`。 。 。 . |
| **获取包 Loss ()** | 返回已测量的包损失比率的减少值(0至1)。 需要一个 `packetLoss` 计量集. |
| **获取 Packet Loss 细节( )** | 返回带有数据包损失测量细节的对象。 包括下列领域: `{ packetLoss, totalMessages, numMessagesSent, lostMessages }`要求 `packetLoss` 计量集. |
| **获取总任务数( )** | 返回引擎运行的全部时间(以毫秒计),不包括任何被暂停的时间。 仅在引擎完成后可用. |
| **获取分数( )** | 返回计算 [AIM 分数](https://developers.cloudflare.com/fundamentals/speed/aim/) 将网络连接的质量按照流化、游戏或实时通信等使用案例分类。 这个分数只有在发动机完成所有测量后才能得到. 没有 `packetLoss` 测量,包损失被忽略在分数之外,所以出值低于5%以下的连接。 失败 `packetLoss` 测量计为0分. |

## 常见问题

### @cloudflare/speedtest 是什么？

对 Cloudflare 的边缘网络进行网络速度测试的组件

### 如何安装 @cloudflare/speedtest？

在项目目录运行 npm install @cloudflare/speedtest，或使用 pnpm add / yarn add / bun add。

### @cloudflare/speedtest 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudflare/speedtest 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cloudflare/speedtest 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudflare/speedtest 可以商用吗？

@cloudflare/speedtest 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudflare/speedtest 的下载量有多少？

根据 npm 官方下载统计，@cloudflare/speedtest 在 2026/10/10 – 2026/11/08 这 30 天内被下载 358,293 次，日均约 11,943 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudflare/speedtest 还在维护吗？

最新版本 1\.17\.0 发布于 2026/11/09（今天）；至今共发布 48 个版本，其中过去 12 个月发布了 20 个；首次发布于 2023/02/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。