Skip to content

构建报告 ​

使用 devtools: { mode: 'report' } 时,Rolldown 会生成一份构建报告,其中包含关于每次构建的 Markdown 和 JSON 文件。报告展示构建耗时分布、输出内容,以及与上一次构建相比的变化。你可以将该文件夹交给代码代理、自己阅读,或在脚本中使用其中的数据。

实验性

devtools 选项目前处于实验阶段。报告格式在后续版本中可能会变化。生成报告需要 Rolldown 1.3.0 或更高版本。

为什么需要构建报告 ​

默认的 'full' 模式会将每个构建事件及各模块的源文本写入日志,供 Vite DevTools 等可视化工具使用。代码代理不需要可视化界面。只有这份日志时,代理必须编写脚本,从大型应用中可能达到数 GB 的文件里提取数据。这会占用 token 和上下文窗口空间。

这份报告是为代码代理设计的。Rolldown 会计算插件耗时、构建变化和保留大小等数据,由代理读取结果。代理会先查看 entry.md(下方构建中为 1.6 KB),只在需要时再打开其他文件。用户和脚本也可以使用这份报告。

下表展示了基准测试仓库中 apps/10000 的一次构建:

devtools写入数据构建耗时
关闭无1.18 s
mode: 'report'4.5 MB1.59 s
mode: 'full'185 MB1.59 s

构建耗时是在 Apple M3 Max 上构建 5 次所得的中位数,其中包含 Node.js 启动耗时。两种模式收集相同的事件,因此都会拖慢构建。只在调查构建情况时启用报告。

4.5 MB 中的大部分是 module-graph.json。代码代理和脚本会查询该文件,而不会完整读取它。所有 Markdown 文件加起来只有 14 KB,因为大多数列表只保留前 20 项。

用法 ​

js
import { defineConfig } from 'rolldown';

export default defineConfig({
  input: 'src/main.js',
  devtools: { mode: 'report' },
});
js
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rolldownOptions: {
      devtools: { mode: 'report' },
    },
  },
});
sh
$ rolldown src/main.js -d dist --devtools.mode report

Vite 8 使用 Rolldown。要查看项目使用的 Rolldown 版本,请运行 npm ls rolldown。

报告位置 ​

Rolldown 会将报告写入相对于 cwd 的 node_modules/.rolldown/report/<output dir>/。<output dir> 是相对于 cwd 的输出目录(output.dir、output.file 所在目录或 dist)。其中每个 .. 都会替换为 __:

输出目录报告目录
distnode_modules/.rolldown/report/dist/
../outnode_modules/.rolldown/report/__/out/

每个输出目录都有自己的报告。

bundle 关闭时,Rolldown 才会写入报告。build()、CLI 和 vite build 都会关闭 bundle。使用 rolldown() API 时,请调用 bundle.close():

js
import { rolldown } from 'rolldown';

const bundle = await rolldown({
  input: 'src/main.js',
  devtools: { mode: 'report' },
});
await bundle.write({ dir: 'dist' });
await bundle.close(); // Rolldown writes the report here

阅读构建报告 ​

本例为 apps/10000 添加了一个插件。该插件只处理 .css 文件,但没有钩子过滤器,因此 Rolldown 会对每个模块都运行它。

rolldown.config.js
js
export default defineConfig({
  // ... the config of the app
  devtools: { mode: 'report' },
  plugins: [
    {
      name: 'my-css-plugin',
      transform(code, id) {
        if (!id.endsWith('.css')) return;
        // ... transform CSS
      },
    },
  ],
});

从 entry.md 开始 ​

摘要会展示主要数据,以及接下来要打开的文件:

entry.md
text
Build 843.6 ms · output 1.8 MB · 20014 modules (10002 external) / 1 chunk / 1 asset / 4 packages · browser / es · build #1

9 plugin hooks did no work in any call — a hook filter would skip those calls (`timing.md`, "Hooks that did no work")

在 timing.md 中查找原因 ​

以下是 hook 表格的前几行:

插件Hook调用次数无操作次数耗时
my-css-plugintransform1001210012 (100%)307.99 s
builtin:data-urlresolveId5001350013 (100%)812.4 ms
builtin:oxc-runtimeresolveId5001350013 (100%)763.7 ms

my-css-plugin 的 10012 次调用都没有执行任何工作,因此应优先处理这个 hook。需要注意两点:

  • 307.99 s 远大于 843.6 ms 的构建耗时。该列是所有调用的耗时总和,每次调用还包含等待 JavaScript 线程的时间。不要将这一列当作构建耗时。
  • builtin:* hook 在 Rust 中运行,因此它们的无操作调用开销很小。

在 delta.md 中查看结果 ​

添加过滤器后重新构建。过滤器为何有帮助,请参阅为什么需要插件 Hook 过滤器?。

js
transform: {
  filter: { id: /\.css$/ },
  handler(code, id) {
    // ... transform CSS
  },
},

delta.md 会将本次构建与上一次构建进行比较:

指标上一次当前ΔΔ%
build.scan_ms452.5 ms427.9 ms-24.5 ms-5.4%
build.total_ms843.6 ms810.6 ms-33.0 ms-3.9%
plugins.hook_call_count190086180074-10012-5.3%
plugins.hook_time_ms310.71 s2.64 s-308.07 s-99.2%

要衡量这项变化,请看 build.total_ms,而不是 plugins.hook_time_ms。hook 耗时虽然下降了 99%,但大部分时间都花在等待上。

一组构建也会受到噪声影响。在这类构建的 5 组对比中,耗时降幅为 3.9% 到 6.7%。要验证改动,请固定基线,然后运行多次构建。

Rolldown 如何生成报告 ​

构建期间,Rolldown 会在内存中将事件转换为数量、大小、图表和耗时数据,不会保留模块源文本。bundle 关闭时,Rolldown 会将文件写入磁盘。

buildBuildscan, generatememoryMemorycounts, sizes,graphs, timingsbuild->memoryeventsfolderReport folderentry.md, metrics.json,.state.json, ...memory->folderbundle closesnextNext buildfolder->nextcompare with.state.json
buildBuildscan, generatememoryMemorycounts, sizes,graphs, timingsbuild->memoryeventsfolderReport folderentry.md, metrics.json,.state.json, ...memory->folderbundle closesnextNext buildfolder->nextcompare with.state.json
  • metrics.json 保存各项数据,Markdown 文件展示其中一部分。
  • module-graph.json 和 chunk-graph.json 保存完整图表,数据量太大,无法放进 Markdown 列表。
  • .state.json 保存本次构建的数据。Rolldown 会将下一次构建与此文件比较,并生成 delta.md。

文件 ​

先查看 entry.md。它会概述构建情况,并告诉你接下来要打开哪个文件。

文件内容
entry.md构建耗时、输出大小、模块、chunk 和 package 数量,以及与上一次构建相比的变化。
timing.md扫描与生成耗时、各 hook 的插件耗时、未执行工作的 hook,以及插件 transform hook 中最慢的模块。
chunks.md最大的 chunk、每个 chunk 存在的原因,以及出现在多个 chunk 中的模块。
modules.md导入类型、导入次数最多的模块,以及多个入口共享的模块。
packages.md最大的 package、直接和传递依赖,以及存在多个版本的 package。
graph.md入口点、chunk 导入图、各入口的初始加载内容,以及保留大小。
delta.md与上一次构建和固定基线相比的变化。Rolldown 从第二次构建起生成此文件。
metrics.json本次构建的数据,包含 output.total_bytes、build.total_ms 等稳定的指标 id。可在脚本中使用。
module-graph.json完整模块图:每个模块的大小、导入项和保留大小。
chunk-graph.json每个输出 chunk 的文件名、大小、入口标记和导入项。
history.jsonl每次构建对应一行摘要。
AGENTS.md提供给读取此文件夹的代码代理的指令。
.state.json本次构建的数据。Rolldown 会将下一次构建与此文件比较。

如何理解数据 ​

  • build.total_ms 包含 scan 和 generate 阶段,数值小于 CLI 显示的总耗时。
  • 报告中 1 kB 等于 1024 字节,CLI 中 1 kB 等于 1000 字节。因此,同一个 chunk 在 CLI 中可能显示为 271.50 kB,在报告中则显示为 265.1 kB。
  • Rolldown 会在 generateBundle hook 运行前、压缩前测量 chunk 和资源大小。这些大小不包含 sourcemap 文件,也不包含 generateBundle 或 writeBundle hook 添加或编辑的文件。
  • 模块和 package 的大小包含 tree shaking 后、renderChunk hook 和 chunk 压缩前的渲染代码。如果一个模块出现在多个 chunk 中,其大小会计入每个副本。
  • 入口的初始加载内容包括其 chunk,以及它直接或间接静态导入的所有 chunk。
  • 直接依赖是指由 cwd 下、node_modules 外的模块导入的 package。其他 package 都是传递依赖。Rolldown 根据导入图判断依赖关系,而不是读取 package.json 中的依赖字段。
  • 大多数列表只保留前 20 项。module-graph.json 包含所有模块,chunk-graph.json 包含所有 chunk。
  • 插件耗时包括 resolveId、load、transform 和 renderChunk。每项耗时是同时运行的调用耗时之和,因此可能远大于构建耗时。timing.md 中的 Transform hotspots 表不包含 Rolldown 核心中的 TypeScript 和 JSX 转换。
  • 无操作调用是指未执行工作的 hook 调用:resolveId、load 或 renderChunk 未返回结果,或者 transform 未返回结果或返回了相同代码。对于 JavaScript 插件,每次无操作调用仍会从 Rust 跨到 JavaScript。Hook 过滤器会跳过这些调用,因此报告中不会包含它们。内置插件(builtin:*)在 Rust 中运行,所以其无操作调用开销很小。

保留大小 ​

模块的保留大小是该模块自身大小加上仅由它引入的模块大小。它估算将该模块的所有静态导入改为 import() 后,可以从静态初始加载中移除的渲染代码字节数。Rolldown 会根据所有用户定义的入口计算该值,但它无法预测压缩后的下载量或加载耗时。

在此示例中,a.js 和 b.js 都导入 shared.js,只有 a.js 导入 heavy.js:

cluster_retainedRetained by a.js: 210.1 kBmainmain.jsbb.js5.0 kBmain->baa.js10.0 kBmain->asharedshared.js50.0 kBb->shareda->sharedheavyheavy.js200.0 kBa->heavy
cluster_retainedRetained by a.js: 210.1 kBmainmain.jsbb.js5.0 kBmain->baa.js10.0 kBmain->asharedshared.js50.0 kBb->shareda->sharedheavyheavy.js200.0 kBa->heavy

graph.md 展示了结果:

模块自身保留大小模块数经由
src/a.js10.0 kB210.1 kB2src/main.js
src/heavy.js200.0 kB200.0 kB1src/a.js
src/shared.js50.0 kB50.0 kB1src/main.js
src/b.js5.0 kB5.0 kB1src/main.js

a.js 的保留大小不包含 shared.js,因为 b.js 也会导入它。via 指所有导入路径到达该模块前都会经过的最后一个模块。

要验证该数据,请将 main.js 对 a.js 的导入替换为 import()。随后,delta.md 中的 Per-entry initial load 表会显示变化:

入口上一次当前ΔΔ%
src/main.js265.1 kB55.2 kB-210.0 kB-79.2%

请查看此表,而不要看 output.max_initial_load_bytes。该指标采用最大的入口;此时 src/a.js 也成为入口,其初始加载大小为 265.3 kB。要同时计算多个模块移出初始加载后的变化,请使用 perf-kit 命令。

比较构建 ​

Rolldown 会将每次构建与同一输出目录的上一次构建进行比较。要与某次指定的构建比较,请将该构建固定为基线:

sh
$ cd node_modules/.rolldown/report/dist
$ cp .state.json baseline.json

之后,Rolldown 还会在 delta.md 和 metrics.json(baselineDelta)中,将后续每次构建与该基线进行比较。要取消固定基线,请删除 baseline.json。

在脚本中使用数据 ​

metrics.json 中的 metrics 是一个扁平映射,包含稳定的指标 id。id 后缀表示单位:_ms 表示毫秒,_bytes 表示字节,没有后缀则表示数量。报告文件夹中的 AGENTS.md 列出了所有 id。

sh
$ cd node_modules/.rolldown/report/dist

# Read one number
$ jq '.metrics["output.total_bytes"]' metrics.json
1887396

# Fail a CI step when the output is too large (`-e` exits with 1 on false)
$ jq -e '.metrics["output.total_bytes"] < 2000000' metrics.json
true

# Show the JavaScript plugin hooks in the top no-op hooks
$ jq -r '.noopHooks[] | select(.plugin | startswith("builtin:") | not) | "\(.plugin) \(.hook) \(.noopCalls)/\(.calls)"' metrics.json
my-css-plugin transform 10012/10012

其他 JSON 数据包含以下字段:

数据字段
delta.metrics 和 baselineDelta.metrics,每个 idprev、curr、delta、pct
modules in module-graph.jsonid, bytes, retainedBytes, retainedModuleCount, idom, staticReachable, dynamicOnly, imports (each is [targetIndex, isDynamic])
chunks in chunk-graph.jsonfileName, name, bytes, isEntry, facadeModuleId, imports, dynamicImports

限制 ​

  • watch()、rolldown --watch 和开发引擎(experimental.devMode)不会生成报告。
  • 一次构建会生成报告或 devtools 日志(默认的 mode: 'full'),不会同时生成两者。
  • 报告位于 node_modules 中,因此全新安装会将其与固定基线一起删除。
  • 一个 bundle 只会生成一份报告:当 bundle 写入多个输出时,第一个输出决定报告目录,报告描述最后一个输出。

相关工具 ​

  • 默认的 'full' 模式会写入完整的 devtools 事件日志。需要查看 @rolldown/debug 或 Vite DevTools 中的所有事件时,请使用此模式。
  • bundleAnalyzerPlugin 会在输出目录中生成一份 chunk 和模块分析文件。构建报告还会提供构建与插件耗时、package 数据和构建间的变化。Rolldown 会将报告写在输出目录之外。
  • @rolldown/perf-kit 可测量页面加载、服务器启动和 Cloudflare Worker 启动耗时,帮助代码代理加快应用启动。它会读取 module-graph.json 以查找可延后加载的代码,并读取 chunk-graph.json 以查找启动较晚的 chunk。

Was this page helpful?