构建报告
使用 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 MB | 1.59 s |
mode: 'full' | 185 MB | 1.59 s |
构建耗时是在 Apple M3 Max 上构建 5 次所得的中位数,其中包含 Node.js 启动耗时。两种模式收集相同的事件,因此都会拖慢构建。只在调查构建情况时启用报告。
4.5 MB 中的大部分是 module-graph.json。代码代理和脚本会查询该文件,而不会完整读取它。所有 Markdown 文件加起来只有 14 KB,因为大多数列表只保留前 20 项。
用法
import { defineConfig } from 'rolldown';
export default defineConfig({
input: 'src/main.js',
devtools: { mode: 'report' },
});import { defineConfig } from 'vite';
export default defineConfig({
build: {
rolldownOptions: {
devtools: { mode: 'report' },
},
},
});$ rolldown src/main.js -d dist --devtools.mode reportVite 8 使用 Rolldown。要查看项目使用的 Rolldown 版本,请运行 npm ls rolldown。
报告位置
Rolldown 会将报告写入相对于 cwd 的 node_modules/.rolldown/report/<output dir>/。<output dir> 是相对于 cwd 的输出目录(output.dir、output.file 所在目录或 dist)。其中每个 .. 都会替换为 __:
| 输出目录 | 报告目录 |
|---|---|
dist | node_modules/.rolldown/report/dist/ |
../out | node_modules/.rolldown/report/__/out/ |
每个输出目录都有自己的报告。
bundle 关闭时,Rolldown 才会写入报告。build()、CLI 和 vite build 都会关闭 bundle。使用 rolldown() API 时,请调用 bundle.close():
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 会对每个模块都运行它。
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 开始
摘要会展示主要数据,以及接下来要打开的文件:
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-plugin | transform | 10012 | 10012 (100%) | 307.99 s |
builtin:data-url | resolveId | 50013 | 50013 (100%) | 812.4 ms |
builtin:oxc-runtime | resolveId | 50013 | 50013 (100%) | 763.7 ms |
my-css-plugin 的 10012 次调用都没有执行任何工作,因此应优先处理这个 hook。需要注意两点:
- 307.99 s 远大于 843.6 ms 的构建耗时。该列是所有调用的耗时总和,每次调用还包含等待 JavaScript 线程的时间。不要将这一列当作构建耗时。
builtin:*hook 在 Rust 中运行,因此它们的无操作调用开销很小。
在 delta.md 中查看结果
添加过滤器后重新构建。过滤器为何有帮助,请参阅为什么需要插件 Hook 过滤器?。
transform: {
filter: { id: /\.css$/ },
handler(code, id) {
// ... transform CSS
},
},delta.md 会将本次构建与上一次构建进行比较:
| 指标 | 上一次 | 当前 | Δ | Δ% |
|---|---|---|---|---|
build.scan_ms | 452.5 ms | 427.9 ms | -24.5 ms | -5.4% |
build.total_ms | 843.6 ms | 810.6 ms | -33.0 ms | -3.9% |
plugins.hook_call_count | 190086 | 180074 | -10012 | -5.3% |
plugins.hook_time_ms | 310.71 s | 2.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 会将文件写入磁盘。
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 会在
generateBundlehook 运行前、压缩前测量 chunk 和资源大小。这些大小不包含 sourcemap 文件,也不包含generateBundle或writeBundlehook 添加或编辑的文件。 - 模块和 package 的大小包含 tree shaking 后、
renderChunkhook 和 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:
graph.md 展示了结果:
| 模块 | 自身 | 保留大小 | 模块数 | 经由 |
|---|---|---|---|---|
src/a.js | 10.0 kB | 210.1 kB | 2 | src/main.js |
src/heavy.js | 200.0 kB | 200.0 kB | 1 | src/a.js |
src/shared.js | 50.0 kB | 50.0 kB | 1 | src/main.js |
src/b.js | 5.0 kB | 5.0 kB | 1 | src/main.js |
a.js 的保留大小不包含 shared.js,因为 b.js 也会导入它。via 指所有导入路径到达该模块前都会经过的最后一个模块。
要验证该数据,请将 main.js 对 a.js 的导入替换为 import()。随后,delta.md 中的 Per-entry initial load 表会显示变化:
| 入口 | 上一次 | 当前 | Δ | Δ% |
|---|---|---|---|---|
src/main.js | 265.1 kB | 55.2 kB | -210.0 kB | -79.2% |
请查看此表,而不要看 output.max_initial_load_bytes。该指标采用最大的入口;此时 src/a.js 也成为入口,其初始加载大小为 265.3 kB。要同时计算多个模块移出初始加载后的变化,请使用 perf-kit 命令。
比较构建
Rolldown 会将每次构建与同一输出目录的上一次构建进行比较。要与某次指定的构建比较,请将该构建固定为基线:
$ 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。
$ 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,每个 id | prev、curr、delta、pct |
modules in module-graph.json | id, bytes, retainedBytes, retainedModuleCount, idom, staticReachable, dynamicOnly, imports (each is [targetIndex, isDynamic]) |
chunks in chunk-graph.json | fileName, 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。