# @chainsafe/benchmark 中文文档

规范地址：https://npmcn.com/package/%40chainsafe/benchmark/

版本：2\.1\.0
npm 元数据更新时间：2026-09-17T21:27:53.543Z
中文译文更新时间：2026-11-09T09:35:15.734Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：234 kB，145 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：13 个
- 首次发布：2025-01-10T13:58:04.412Z
- 最新版本发布：2026-09-17T21:27:53.218Z
- 近 30 天下载量：15324（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 2 个）

## 中文简介

> 这是独立维护的叉子 [@ dapplion/ 基准](https://github.com/dapplion/benchmark)。这个Repo现在维持它自己的版本为 `@chainsafe/benchmark` 和释放时间表。 它来自QQdapplion/基准@1的基座

## 安装

```sh
npm install @chainsafe/benchmark
```

也可以使用：`pnpm add @chainsafe/benchmark`、`yarn add @chainsafe/benchmark`、`bun add @chainsafe/benchmark`

## README

# 基准

> 这是独立维护的叉子 [@ dapplion/ 基准](https://github.com/dapplion/benchmark)。 。 。 . 这个Repo现在维持它自己的版本是: `@chainsafe/benchmark` 和释放时间表。 它从基地被铲出 `@dapplion/benchmark@1.0.0` 并增加了新的功能.

确保新代码不引入 CI 的性能回归. 音轨 :

-   对基准分支的PR是否包含性能回归?
-   主分支的新承诺是否包含性能回归?

这种工具既便于用于制定基准,也便于整合过去的基准数据.

## 快开始

创建基准测试文件但使用 `itBench` 改为 `it`

```ts
import {describe, itBench, setBenchOpts} from "@chainsafe/benchmark";

describe("Sum array benchmark", () => {
  itBench("sum array with reduce", () => {
    arr.reduce((total, curr) => total + curr, 0);
  });
});
```

然后运行CLI.

```
benchmark 'test/perf/**/*.perf.ts' --local
```

终端检查基准结果

```
  Sum array benchmark
    ✔ sum array with reduce                                               826.0701 ops/s    1.210551 ms/op   x0.993        578 runs   1.21 s
```

## 怎么会这样?

此工具是一个 CLI 工具, 例如使用 :

```
benchmark 'test/perf/**/*.perf.ts' --s3
```

上述命令将:

-   从指定的提供者( AWS S3) 读取基准历史
-   根据您的选项计算出预览基准( 默认为主分支的最新承诺)
-   运行基准与上一个比较
    -   在流出结果时收集基准数据
-   将结果添加到基准历史,并持续到指定的提供者(AWS S3)
-   如果在CI中张贴一份PR或承诺,并附上可扩展的基准结果比较摘要
-   如果检测到性能回归, 退出 1

### CI 中的音轨性能

以下是 Github 与 S3 历史提供者运行此工具的建议动作 :

```yaml
name: Benchmark
# Ensure a single benchmark is run at a time
concurrency: cd-benchmark-${{ github.ref }}

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  s3:
    if: always()
    runs-on: ubuntu-latest
    # Ensure both don't run at the same time
    needs:
      - local
      # - ga-cache

    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2-beta
      - run: yarn install --frozen-lockfile

      # Run benchmark with custom tooling and stores the output to a file
      - name: Run performance tests
        run: yarn benchmark --s3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # S3 credentials
          S3_ACCESS_KEY: ${{ secrets.S3_ACCESS_KEY }}
          S3_SECRET_KEY: ${{ secrets.S3_SECRET_KEY }}
          S3_REGION: ${{ secrets.S3_REGION }}
          S3_BUCKET: ${{ secrets.S3_BUCKET }}
          S3_ENDPOINT: ${{ secrets.S3_ENDPOINT }}
          # Key prefix to separate benchmark data from multiple repositories
          S3_KEY_PREFIX: ${{ github.repository }}/${{ runner.os }}
```

### 本地音轨性能

当您努力优化某个函数时, 您可能想知道您的代码是否实际上比先前的执行更快 .

要做到这一点, 您可以在本地保存一个基准历史文件, 并比照先前的代码先运行基准

```
git checkout master
benchmark test/perf/func.perf.ts --local
```

-   不与上一个比较而运行基准
-   将单一基准数据写入 `./benchmark_data`

然后用新代码测量性能

```
git checkout fix1
benchmark test/perf/func.perf.ts --local
```

-   从 `./benchmark_data`
-   运行基准与预览比较
-   不写入基准数据

### 孤立基准文件( Node.js)

使用 `--isolate` 以新进程而不是默认共享进程依次运行每个文件:

```sh
benchmark 'test/perf/**/*.perf.js' --isolate --historyLocal ./benchmark_data-isolated
```

每个工人都继承可执行的节点、运行时旗(包括加载器和 `--expose-gc`),环境,和工作目录. 每个工人都有文件 下个文件只从之前的工人退出后才开始,释放出其所保留的内存和本土资源. 已完成的工人即使基准代码留下了开口的手柄也退出.

家长仍然拥有历史,综合快照,性能比较,以及单张GitHub报告. 收集失败、基准失败、坠机、工人结果缺失、中断、以及文件重复ID等 `--noThrow`。允许跳过的文件,但整个运行必须至少产生一个结果.

文件必须是独立的:全局和钩子不跨文件共享,以及 `.only` 选择每个文件都是本地的。 跨文件使用独有的基准标识 。 切换模式时,使用新鲜的本地历史路径 CI 缓存键,或 S3 前缀;共享进程和孤立的测量不是可互换的基线. 历史命名空间不会自动更改 .

## 配置

### `--isolate`

在新进程中依次运行每个文件

-   类型:布尔
-   默认: 假

### `--defaultBranch`

提供此寄存器的默认分支, 以防止从 Github 取取

-   类型:字符串
-   默认 :

### `--persistBranches`

选择要坚持基准数据的分支

-   类型:数组
-   默认: 默认分支

### `--benchmarksPerBranch`

限制每个分支机构的基准数目

-   类型:数量
-   默认: 无穷

### `--threshold`

每跑新平均时间与每跑预估时间之比考虑失败. 设定为“ 无穷” 以禁用 .

-   类型:数量
-   默认: 2

### `--compareBranch`

将新的基准数据与本分支最新可用基准进行比较

-   类型:字符串
-   默认: 默认分支

### `--compareCommit`

将新基准数据与具体承诺的相关基准数据进行比较

-   类型:字符串
-   默认 :

### `--prune`

当持续历史时,删除与当前 git 历史中不再存在的承诺有关的基准数据

-   类型:布尔
-   默认 :

### `--persist`

历史上一直存在的基准数据

-   类型:布尔
-   默认 :

### `--noThrow`

即使找到预态回归, 也干净退出

-   类型:布尔
-   默认 :

### `--historyLocal`, (中文(简体) ), `--local`

坚持本地基准历史. 可以指定仅使用默认路径的布尔, 或提供路径

-   类型:字符串
-   默认:./基准 数据

### `--historyGaCache`, (中文(简体) ), `--ga-cache`

Github Actions缓存中的持久性基准历史. 需要 Github 认证 。 可能只指定布尔以使用默认缓存密钥或提供自定义密钥

-   类型:字符串
-   默认: 基准 数据

### `--historyS3`, (中文(简体) ), `--s3`

亚马逊S3水桶中的持久基准历史. 需要 Github 认证

-   类型:字符串
-   默认 :

## 路线图

### 比较性能

```
bench compare --from <branch-name | commit-hash> --to <branch-name | commit-hash>
```

-   检索基准历史
-   不要运行基准
-   从基准到基准的打印比较

### 添加更多提供者

-   Github 动作缓存:由于 Github 的局限性而无效
-   提交到寄存器( gh- pages, 或数据分支)

## 常见问题

### @chainsafe/benchmark 是什么？

这是独立维护的叉子 @ dapplion/ 基准。这个Repo现在维持它自己的版本为 @chainsafe/benchmark 和释放时间表。 它来自QQdapplion/基准@1的基座

### 如何安装 @chainsafe/benchmark？

在项目目录运行 npm install @chainsafe/benchmark，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 benchmark，可以用 npx benchmark 直接运行。

### @chainsafe/benchmark 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chainsafe\_\_benchmark 是否存在。

### @chainsafe/benchmark 支持 ESM 还是 CommonJS？

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

### @chainsafe/benchmark 可以商用吗？

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

### @chainsafe/benchmark 的下载量有多少？

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

### @chainsafe/benchmark 还在维护吗？

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