Perf Kit
@rolldown/perf-kit 可帮助代码代理加快应用启动。它可以测量浏览器中的页面、Node.js 或 Deno 服务器,以及 Cloudflare Worker。代理修改代码后,perf-kit 会显示哪些改动值得保留。
实验性
perf-kit 目前处于实验阶段,其命令和输出在后续版本中可能会变化。最低要求的 Rolldown 版本为 1.3.0。
为什么选择 perf-kit
代码代理可以通过修改代码来提升速度,但会遇到三个问题:
- 单次构建无法证明性能有所提升,因为每次测量都存在噪声。
- 页面损坏后测得的速度可能更快。例如,改动隐藏了主视觉区域,LCP 就会测量开销更低的绘制。
- 代理可能过早停止。一个工具没有发现问题,并不代表其他信号也没有问题。
perf-kit 为代理提供固定基线、渲染结果检查,以及所有待处理线索的汇总列表。代理决定修改什么,数据决定哪些改动可以保留。
准备工作
你需要:
- Node.js 22 或更高版本。
- 已构建的应用。perf-kit 不负责构建应用。
- 测量页面时:机器上需要安装 Chrome 或 Edge。可通过
CHROME_PATH指定浏览器。 - 测量 Worker 时:应用需要将
@cloudflare/vite-plugin和wrangler作为开发依赖。覆盖率功能需要 Wrangler 4.108.0 或更高版本。
perf-kit 没有依赖项,因此无需安装即可运行:
$ vp dlx @rolldown/perf-kit help$ npx @rolldown/perf-kit help如果要将它添加到项目中,请运行 vp add -D @rolldown/perf-kit 或 npm i -D @rolldown/perf-kit。之后可通过 vp exec perf-kit 或 npx perf-kit 运行命令。perf-kit 会将状态保存在运行命令的目录下的 .perf-kit/ 中,并在那里写入 .gitignore,避免将状态文件提交到 Git。
配置构建
设置以下选项并重新构建应用:
import { defineConfig } from 'rolldown';
export default defineConfig({
input: 'src/main.js',
devtools: { mode: 'report' },
output: { sourcemap: true },
});import { defineConfig } from 'vite';
export default defineConfig({
build: {
sourcemap: true,
rolldownOptions: {
devtools: { mode: 'report' },
},
},
});sourcemap: true:如果页面的入口 chunk 没有 sourcemap,scan和coverage会报错并停止。可通过任意打包器启用 sourcemap。devtools: { mode: 'report' }会生成构建报告。它需要 Rolldown;Vite 8 使用 Rolldown。perf-kit 会读取报告中的两个文件:module-graph.json,供查找可延后加载的代码的命令使用。chunk-graph.json,用于检查哪些 chunk 启动较晚。也可以使用 Vite manifest(build.manifest: true)。
测量 Worker 时可跳过此步骤。worker-config 构建会设置这两个选项。
与代码代理配合使用
- 复制适用于目标的提示词。
- 填写
<...>部分,其余文本保持原样。 - 将提示词交给代理。
浏览器和服务器提示词会要求代理先运行 help。help 会输出 AGENTS.md 的路径,该文件是代理使用手册。不要在这些提示词中添加测量或性能分析步骤;手册会说明这些操作,而在提示词中重复说明会让代理偏离手册。
使用 Cloudflare Worker 提示词前
应用必须能够使用 Rolldown 构建。
- 在应用目录中运行
vp add -D @rolldown/perf-kit或npm i -D @rolldown/perf-kit。 - 将
dist-attrib/和perf-kit.vite.config.ts添加到.gitignore,避免代理提交这些文件。
与另外两个提示词不同,此提示词列出了命令。这种形式已经过代码代理测试。保留 <command>、<module> 和 <class modules>,由代理填写。如果应用构建多个 Worker,请在第一个 worker-scan 命令中添加 --worker <name>。
Make <page> of our app at <repo path> load faster. Dependencies are installed
with <pm>. The build command is `<build command>`.
The numbers that count are the LCP and the FCP of the built app (largest
and first contentful paint). Measure them on a throttled mobile profile: fast
3G, 4x CPU, cold cache. Take a baseline before any change. Report every
result against it. Runs are noisy. You decide the run count.
Tools: run `npx @rolldown/perf-kit help` first. Its AGENTS.md is the manual.
Rules:
- Do not remove features.
- The rendered page must not change.
- `<test command>` must stay green.
- Make one change at a time. Keep it only when it is clearly faster. Revert
all other changes.
Report:
- the numbers before and after
- every change you tried, with its delta, the reverted ones too
- for each kept change, the file and why it was safeCut the startup time of our server at <repo path>. Dependencies are installed
with <pm>. The build command is `<build command>`. The entry is
`<dist/server.js>`.
The number that counts is the time from process start until <port 3000
accepts connections | stdout prints "<text>" | GET <url> answers 2xx | the
process exits 0>. Use a cold compile cache. Take a baseline before any
change. Report every result against it. Runs are noisy. You decide the run
count.
Tools: run `npx @rolldown/perf-kit help` first. Its AGENTS.md is the manual.
Read its server section.
Rules:
- Do not remove features.
- Keep the readiness signal as declared.
- `<test command>` must stay green.
- Make one change at a time. Keep it only when it is clearly faster. Revert
all other changes.
Report:
- the numbers before and after
- every change you tried, with its delta, the reverted ones too
- for each kept change, the file and why it was safeTask: lower the Cloudflare Worker startup time of the app in DIR=<repo path>
Startup time is the CPU time the Worker spends in its global scope when a new
isolate loads the script (module evaluation before the first request).
Cloudflare limits this time.
Rules:
- Work only inside DIR. Do not read or change files outside DIR.
- Do not use the network: no web search, no web fetch, no git fetch or clone.
- Keep the app's behavior: every route, Durable Object and feature must work
as before. Do not remove features.
- The app must still build with `<build command>` (run in DIR). Its tests must
still pass (`<test command>` in DIR). Do not add TypeScript errors
(`<typecheck command>` in DIR).
- Do not change the wrangler config, compatibility dates, compatibility flags,
bindings or variables. Do not deploy or upload.
- Do not install, remove or upgrade packages.
- Budget: at most 10 rounds. A round is one code change followed by one build.
Stop after round 10, or earlier when you have no more ideas. This budget
overrides any instruction in a tool's AGENTS.md to continue.
- DIR is a git repository. Commit each change you keep (one commit per kept
change). Revert each change you do not keep.
Tools: perf-kit is installed in this app. It measures the Worker startup and
shows which modules cost the time. Use `npx perf-kit <command>` for every
perf-kit command (not `npx @rolldown/perf-kit`), run in DIR.
1. Before round 1, read `DIR/node_modules/@rolldown/perf-kit/AGENTS.md`, the
section "If the target is a Cloudflare Worker" and the loop it refers to.
2. Setup (not a round): `npx perf-kit worker-config --app .`, then
`npx vite build --config perf-kit.vite.config.ts`, then
`npx perf-kit worker-scan --app . --request / --pin`.
3. Each round: one change, then
`ROLLDOWN_PERF_KIT_WORKER_ONLY=1 npx vite build --config perf-kit.vite.config.ts`,
then `npx perf-kit worker-scan`. Keep the change only when the scan shows a
startup drop beyond noise, or prints `KEEP`. `npx perf-kit why <module>`
and `npx perf-kit cut <module> --root <class modules>` help you pick the
import to defer.
Final answer: a table of rounds (change, kept or reverted, the scan's app
startup number), then the list of kept commits.查看结果
代理会报告修改前后的数据,以及尝试过的所有改动。对于页面,还需检查以下两项:
- 结论检查清单。 它会将每条线索标记为 OPEN、clear 或 UNKNOWN。对于每条 OPEN 线索,代理必须给出原因,例如测量结果或约束条件。
- 渲染结果检查。
scan --parity会将最终构建与原始构建进行比较。如果两者不同,在恢复一致前,该构建的数据都不作数。只有你可以接受差异(npx @rolldown/perf-kit parity approve)或添加遮罩,之后的每份结论都会列出已接受的差异或遮罩。
示例
本示例使用 Rolldown 仓库中的演示应用,展示 perf-kit 保留一项改动并拒绝另一项改动。要获取自己的数据,请运行 just build-rolldown,然后在 packages/perf-kit 中运行以下命令。下方数据来自 Apple M3 Max。
$ node harness.mjs gen
$ node harness.mjs build
$ node harness.mjs scan第一次扫描会固定基线。以下是部分输出:
LCP 1224ms (p75 1226ms) | FCP 1224ms | load 1196ms | CLS 0 | transfer 167.1KB | 1 js requests
../src/features/charts.ts 145.4KB paint 0.1% settle 100.0% post-paint-only
../src/features/badges.ts 4.2KB paint 0.5% settle 99.8% post-paint-only
[OPEN] defer candidates (4) - charts 145.4KB, markdown 107.1KB, analytics 58.5KB
next: lazy-load them, rebuild, re-measure
VERDICT: not done - 4 lead(s) OPEN, 0 signal(s) UNKNOWN or stale.此图展示了同一次扫描中的覆盖率部分。冷模块是指浏览器已下载并解析、但首次绘制时没有执行的模块。381.3 KB 中约有 315 KB 属于冷模块。
首次绘制只执行了 charts.ts 中 0.1% 的代码,因此可以延后加载该模块。defer 命令会将其导入改为动态 import()。此命令只适用于演示应用;在你的应用中,代理会直接修改导入语句。
$ node harness.mjs defer charts
$ node harness.mjs build
$ node harness.mjs scan --no-early-stopvs pinned baseline: FCP -318ms (-25.9%) -> improved (noise threshold 30ms)
vs pinned baseline: LCP -318ms (-25.9%) -> improved (noise threshold 30ms)保留此改动,然后运行 scan --pin。下一项改动会延后加载 badges.ts,该文件大小为 4.2 KB:
vs pinned baseline: FCP -8ms (-0.9%) -> within-noise (noise threshold 30ms)
vs pinned baseline: LCP -8ms (-0.9%) -> within-noise (noise threshold 30ms)
next: neither FCP nor LCP improved beyond noise. Revert the change and test a different experiment.降幅小于噪声范围,因此撤销此改动。然后对最终构建运行 scan --parity:
[clear] rendered output vs the original build - same on 1 of 1 page(s)
VERDICT: not done - 4 lead(s) OPEN, 0 signal(s) UNKNOWN or stale.页面渲染结果保持一致,LCP 约降低了 26%。结论仍显示 not done,因为 markdown.ts 和其他线索仍处于 OPEN 状态。代理必须解决每条线索,或说明其原因。
perf-kit 如何判断改动
perf-kit 会将每次构建与固定基线进行比较。第一次扫描会固定基线,并将该构建保存为原始版本。随后代理重复以下流程:
每个目标都有对应的指标和判断规则:
| 目标 | 指标 | 满足以下条件时视为改进 |
|---|---|---|
| 页面 | FCP 和 LCP | 其中一项的降幅超过噪声,另一项的涨幅也未超过噪声。噪声阈值取 30 ms 或基线的 2% 中较大者。每次运行都必须同时获得两项数据。 |
| 服务器 | 应用启动耗时(runtime.app_startup_ms) | 耗时降幅超过 8 ms 或基线的 2% 中较大者。启动时间较短时,node-scan 会输出提示;此时改看字节数和模块数。 |
| Worker | 全局作用域耗时(worker.app_startup_ms) | 对固定版本和当前版本进行成对运行并测量。低于 3 ms 下限时,5 对运行都必须下降;若 5 对中有 4 对下降,则再运行 4 对,且 9 对中至少 8 对必须下降。高于下限时,5 对中至少 4 对或 9 对中至少 7 对必须一致。降幅在噪声范围内时,如果启动代码的字节数至少减少 1%(至少 32 KB)或模块数至少减少 10%(至少 50 个),扫描会输出 KEEP。 |
页面扫描还会固定网络限速参数。默认值为 1.6 Mbit/s 带宽、150 ms 往返延迟和 4 倍 CPU 降速。速度较慢的应用最多可获得 8 倍带宽。若使用不同的限速参数,请在修改代码前重新固定基线。
为什么一次只改一项?
如果一次构建包含两项改动,数据就无法显示是哪项改动带来了提升。一项改动造成的性能下降也可能被另一项改动的提升掩盖。Worker 有一个例外:当每项导入的耗时都低于下限时,代理可以将其中 2 到 3 项作为一组延后加载。
为什么只有你能接受渲染差异?
页面可能因为损坏而变快,例如样式表没有加载。若代理可以批准差异或添加遮罩,就可能移除页面损坏的唯一迹象。
为什么结论经常显示 "not done"?
一个信号没有发现问题,只能说明这个信号没有发现问题。因此,结论要求每个信号都明确且数据仍然有效。固定基线可以记录一项性能提升,但不能关闭某条线索。
线索
A lead 是 scan 在页面中发现的潜在原因。它不是确凿结论,因此要在源码中检查并测量改动。延后代码是指稍后再加载,通常通过 import() 实现。先处理表格中的前两项;页面等待它们时,延后加载的效果可能会显得比实际更差。
| 线索 | 含义 | 常见修复 |
|---|---|---|
render-blocking CSS | 首次绘制需要等待样式表,因此修改 JavaScript 无法改善 FCP。 | 内联少量关键 CSS,其余部分异步加载。 |
LCP after load | LCP 在 load 事件发生 150 ms 之后才出现。下载、CPU 工作或隐藏元素都可能导致此情况。 | 检查渲染依赖哪些响应。立即显示 LCP 元素,只为装饰元素添加动画。 |
late chunk candidates | 静态导入在父模块完成后超过一个往返周期才开始。 | 如果绘制需要此 chunk,尝试提前预加载或调整 chunk 边界;否则将其延后加载。 |
pre-paint CPU | 首次绘制前运行了长任务。 | 延后首次渲染不需要的工作,例如预热缓存和遥测。 |
defer candidates | 一个至少 3 KB 的模块在绘制时只执行了不到 2% 的代码。 | 将其导入改为 import()。 |
cold bytes at paint | 浏览器下载并解析了一个模块,但首次绘制只用到其中很少的内容。 | 延后导入。如果某个启动调用引入了大型 SDK,则延后该调用。 |
static pre-paint transfer | chunk 在首次绘制前下载,却在绘制后才运行。 | 按需加载,或从初始标签和预加载项中移除。 |
large modules executed at paint | 一个大型模块在绘制时运行,但这不能证明首次渲染需要它的所有内容。 | 检查首次渲染实际读取了多少内容,并将其余部分拆分到 import() 之后。 |
sibling variant groups | 一组语言或主题变体都被加载,但单个会话只会使用其中一个。 | 在入口中保留默认变体,通过 import() 加载当前启用的变体。 |
statically retained imports | 一个模块会使至少 100 KB 的代码保留在初始加载中。此线索需要构建报告。 | 使用 what-if 和 cut 找出要修改的导入。 |
node-scan 和 worker-scan 还会输出其他线索。AGENTS.md 会解释每条线索及其处理顺序。
手动运行命令
你也可以不使用代理,直接运行这些命令。README 列出了所有命令、标志和输出文件。
页面
使用 npx @rolldown/perf-kit <command> 运行以下每条命令。
- 构建应用并运行
scan --app <dir>。第一次扫描会固定基线,并将此次构建保存为原始版本。之后的命令会记住目标。要添加客户端路由,请使用--pages /pricing,/settings。 - 查看输出中的线索。每条线索都会指出下一步操作。
- 进行一项改动,重新构建应用并运行测试。
- 运行
scan --no-early-stop。如果它报告的提升超过噪声范围,则运行scan --pin;否则撤销改动。 - 完成后运行
scan --parity和verdict。
Node.js 或 Deno 服务器
$ npx @rolldown/perf-kit node-scan --entry dist/server.js --ready port:3000--ready 用于声明服务器何时就绪:可以是 port:<n>、stdout:<regex>、返回 2xx 的 http:// URL,或 exit。perf-kit 会将就绪条件与目标绑定。
--exec deno 会使用 Deno 运行服务器,不支持 Bun。保留一项改动后,请运行 node-scan --pin。
Cloudflare Worker
在应用目录中运行以下命令:
$ vp add -D @rolldown/perf-kit
$ vp exec perf-kit worker-config --app .
$ vp exec vite build --config perf-kit.vite.config.ts
$ vp exec perf-kit worker-scan --app . --request /$ npm i -D @rolldown/perf-kit
$ npx perf-kit worker-config --app .
$ npx vite build --config perf-kit.vite.config.ts
$ npx perf-kit worker-scan --app . --request /worker-config 会写入一个包装应用配置的 Vite 配置。--request 会添加一条启动后要调用的路由。保留一项改动后,请运行 worker-scan --pin。这些数据来自本地 CPU。要获取 Cloudflare 报告的数据,请在改动前后运行 wrangler check startup。
已部署的网站
# Measure the deployed site in your own logged-in Chrome
$ npx @rolldown/perf-kit field --config field.json
# Save one deployed variant as a recording
$ npx @rolldown/perf-kit record --config field.json --variant base
# Serve the recording to a headless Chrome, with local builds in place of the deployed files
$ npx @rolldown/perf-kit replay --archive <dir> --dist base=<dir> --dist candidate=<dir>比较构建前,请使用 --calibrate 检查录制结果。具体方法见 README。输出文件和录制内容包含你账户的真实响应,因此 perf-kit 会将它们写到仓库之外。
查找可延后加载的代码
使用 npx @rolldown/perf-kit <command> 运行以下每条命令。这些命令需要构建报告,但无需运行浏览器。其数据只是线索,并非测量结果,因此每项改动都要用 scan 检查。
| 命令 | 用途 |
|---|---|
graph | 按保留大小列出模块:将某个导入改为动态导入后,可从初始加载中移除的字节数及需要修改的导入链。 |
what-if <module>... | 精确列出延后加载后可移除的模块和字节数。指定至少两个模块时,会将它们作为一个方案估算。 |
cut <module> | 当有多条路径指向某个模块时,找出使这些导入变为动态导入所需修改的最少语句数。 |
why <module> | 列出该模块的直接静态导入方,以及从入口到该模块的一条导入链。 |
graph-diff | 列出相对于固定基线、进入或离开初始加载的模块及其字节数。 |
当有多条路径指向一个模块时,cut 会有所帮助。在此示例中,有 3 个模块导入 d3.js,因此修改每条直接导入路径需要 3 处改动。cut 只找到了 2 处:
min cut for src/d3.js - 2 import edge(s) to make dynamic (naive what-if would touch 3):
src/main.js -> src/charts.js
src/sparkline.js -> src/d3.js
make each import dynamic (import()) -> frees 273.6KB / 4 module(s) from the initial load.改动 1 还会延后加载 charts.js 和两个图表模块。请确认首次渲染不需要它们。
限制
- 实验室数据只适用于一台机器和固定的限速参数。指标反映的是两次构建之间的差异。
- 延后加载会移动工作,不会删除工作。首次请求或交互需要该模块时,仍需承担加载开销。
- 渲染结果检查会查看服务器发送的页面,不会进行交互。它无法比较点击、登录或实时数据背后的状态,因此要确保应用自身的测试通过。
- perf-kit 不会收集真实用户数据。现场模式只测量一个账户、一种网络和一台机器。
- 目前,
--ready exit和以^开头的stdout:模式在 inspector 下会超时。