next-browser-initial-load-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Browser initial-load optimizer

Browser 初始加载优化器

1. Set the scope

1. 确定范围

Choose a route and audit or fix mode. Audit is the default: generate analyzer artifacts and report candidates while leaving application source, dependencies and lockfiles unchanged. Fix mode requires an explicit request to change the app. Ask before changing visible behavior, timing, compatibility or a trust boundary. For a route's static App Shell, use

next-cache-components-optimizer

; for navigation prefetch work, use

next-partial-prefetching-optimizer

Done: the route, mode and intended behavior are recorded. A request to capture or export data is audit mode, not permission to fix.

选择目标路由和 audit 或 fix 模式。默认使用 audit：生成 analyzer 产物并报告候选项，同时不更改应用源代码、依赖和 lockfile。只有在明确要求修改应用时才进入 fix 模式。修改可见行为、时序、兼容性或 trust boundary 前，应先询问。对于某个路由的静态 App Shell，使用

next-cache-components-optimizer

；处理导航预取工作时，使用

next-partial-prefetching-optimizer

。

完成： 已记录路由、模式和预期行为。请求捕获或导出数据属于 audit 模式，并不表示获得了修复授权。

2. Capture and export a baseline

2. 捕获并导出基线

Run from the app directory with its package manager. Read

next analyze --help

for capture options and

next analyze export --help

for replay options in the installed CLI. Reuse a selected saved snapshot, or capture with a distinctive name first; then export it through gzip at its default compression level. Keep before/after

.jsonl.gz

files separate.

Sandbox requirement: If the agent’s sandbox blocks TCP port binding (as Codex’s does), it MUST run the

next analyze --output

capture outside the sandbox. Do not attempt the capture inside that sandbox, even though

--output

does not serve the analyzer UI.

Run the pipeline in Bash:

bash

set -o pipefail

从 app 目录运行，并使用其包管理器。在已安装的 CLI 中，读取

next analyze --help

以了解捕获选项，并读取

next analyze export --help

以了解回放选项。复用已选择的已保存 snapshot，或先使用有辨识度的名称进行捕获；然后通过 gzip 按默认压缩级别导出。将 before/after 的

.jsonl.gz

文件分开保存。

Sandbox 要求： 如果 Agent 的 sandbox 阻止 TCP 端口绑定（如 Codex 的 sandbox），则必须在 sandbox 外运行

next analyze --output

捕获。不要在该 sandbox 内尝试捕获，即使

--output

不会启动 analyzer UI 服务。

在 Bash 中运行以下流水线：

bash

set -o pipefail

Capture only when a new baseline is needed

pnpm exec next analyze --output --snapshot 'audit-before-unique-1' pnpm exec next analyze export --snapshot 'audit-before-unique-1' --route '/dashboard' | gzip > /tmp/analyze-dashboard-before.jsonl.gz


`--output` builds and saves binary/UI artifacts without serving. `next analyze export` reads a saved snapshot without building; stdout is one typed JSON record per line, with errors on stderr. The route filter keeps the whole-app module graph, so scope it in the next step.

For a custom `distDir`, replay with `--dist-dir <configured-directory>` (relative or absolute): capture loads the app config, replay does not. `--snapshot <name>` selects a retained name; omission selects the newest snapshot. Capture generates a unique timestamp name when omitted, and **replaces** an existing capture when an explicit name is reused. Use distinct before/after names, including names with spaces, to preserve both baselines. For interactive exploration, capture without `--output` to serve the UI; `next build --analyze` also produces replayable data.

**Done:** the chosen capture is identified, export succeeded, and the baseline file, snapshot name and selected route are recorded. Check the whole pipeline's exit status before processing the compressed file: `pipefail` prevents gzip from hiding a failed export. Export validates one route at a time, so a failure can leave a partial archive even if `gzip -t` accepts it. Discard output when export or gzip fails.


`--output` 会在不启动服务的情况下构建并保存二进制/UI 产物。`next analyze export` 读取已保存的 snapshot 而不执行构建；stdout 每行输出一条带类型的 JSON 记录，错误写入 stderr。路由过滤器会保留整个应用的模块图，因此需要在下一步中限定范围。

对于自定义 `distDir`，回放时使用 `--dist-dir <configured-directory>`（相对或绝对路径）：捕获会加载 app 配置，回放不会。`--snapshot <name>` 选择保留的 snapshot 名称；省略时选择最新 snapshot。捕获时若省略名称，会生成唯一的时间戳名称；显式复用已有名称则会替换原捕获。使用不同的 before/after 名称，包括带空格的名称，以保留两个基线。需要交互式探索时，不带 `--output` 执行捕获以提供 UI；`next build --analyze` 也会生成可回放的数据。

**完成：** 已明确所选捕获，导出成功，并已记录基线文件、snapshot 名称和选定路由。在处理压缩文件前检查整个流水线的退出状态：`pipefail` 可防止 gzip 掩盖导出失败。导出一次只验证一个路由，因此即使 `gzip -t` 接受文件，失败也可能留下部分归档。导出或 gzip 失败时丢弃输出。

3. Interpret the evidence

3.解读证据

Resolve the schema from the app's installed Next.js, using its Node launcher:

bash

pnpm exec node -p "require.resolve('next/analyze/graph-v1.schema.json')"

Read its descriptions for record meanings, joins, attribution and coverage. Stream decompression with

gzip -dc /tmp/analyze-dashboard-before.jsonl.gz

into a line-oriented analysis script rather than loading the whole dump into context. Use the schema to interpret the selected route's client/server contributions and choose the metric.

Done: the baseline's route-attributed client/server contributions and the metric are identified. Treat this as build evidence: claims about observed browser requests, timing or transfer savings need separate evidence.

使用 Node 启动器，根据应用已安装的 Next.js 解析 schema：

bash

pnpm exec node -p "require.resolve('next/analyze/graph-v1.schema.json')"

读取其中对记录含义、关联方式、归因和覆盖范围的说明。使用

gzip -dc /tmp/analyze-dashboard-before.jsonl.gz

将解压后的数据流式传入按行处理的分析脚本，而不是把整个 dump 加载到上下文中。使用 schema 解读所选路由的客户端/服务端贡献并选择指标。

完成： 已确定基线中按路由归因的客户端/服务端贡献和指标。将其视为构建证据：有关实际观察到的 browser 请求、时序或传输节省的结论需要单独证据。

4. Explain a candidate

4. 解释候选项

Inspect actual project source and exact importers. Start with the named route or rank scoped client-output contributions by attributed size, repetition, likely runtime cost, need before interaction and correctness risk.

检查实际项目源代码和准确的 importer。首先以指定路由为起点，或按归因大小、重复情况、可能的运行时成本、交互前是否必需以及正确性风险，对限定范围内的客户端输出贡献进行排序。

Community → min-cut pass

Community → min-cut 流程

For broad audits seeking opportunities across multiple features or a large contributor list, run community detection → target selection → directed min-cut → source validation after the initial ranking. Read Graph methods before constructing the graph or running solvers.

Rank detected communities by scoped client-output attribution and inspect their inbound importers.
Select large communities, or optional feature regions within them, that can plausibly wait for interaction. Record why each selected region is optional under the route's render conditions.
Run directed min-cuts from the verified client roots to those targets to find small sets of importer changes that could detach them.
Validate the cut edges against source and behavior constraints; account for each investigated target as a candidate, rejected cut or evidence gap.

For a narrow audit of a named dependency or feature, use direct importer reasoning when it fully accounts for the relevant paths and proposed boundary; record why the paired pass adds no useful target discovery. If graph evidence or tooling blocks the pass, record the blocker and limit the conclusions accordingly.

对于需要在多个功能或大量贡献项中寻找机会的广泛审计，在初始排序后运行 community detection → target selection → directed min-cut → source validation。在构建图或运行求解器前，先阅读 Graph methods。

按限定范围内的客户端输出归因对检测到的 community 进行排序，并检查其入站 importer。
选择大型 community，或其中可选的功能区域；这些区域在该路由的渲染条件下有可能等到交互后再加载。记录每个所选区域为何在该路由的渲染条件下是可选的。
从已验证的客户端根节点到这些目标运行 directed min-cut，找出可能使目标脱离依赖图的一小组 importer 变更。
根据源代码和行为约束验证割边；对每个已调查目标记录其处置结果：候选项、被否决的割或证据缺口。

对于针对指定依赖或功能的窄范围审计，如果直接分析 importer 已能完整涵盖相关路径和拟议边界，则采用直接 importer 推理；并记录为何配对流程不会发现额外目标。如果图证据或工具阻碍该流程，记录阻塞项并相应限制结论。

Graph-evidence checklist

图证据检查清单

Before proposing an edit, record these items for each candidate. Mark an inapplicable item with its reason; give missing evidence an explicit gap.

Scope: name the route, snapshot, render conditions, client/server output class, exact target identities and metric. For reachability claims, identify every selected client root, including applicable client references.
Coverage: summarize relevant unsupported outputs and unresolved references, with available reasons and their effect on the claim. Scope conclusions to the known subgraph when completeness is uncertain.
Attribution: count each selected output contribution once. Record repeated-record handling and distinguish source paths from module identities; explain any mapping used for solver weights and preserve unknown weights as gaps.
Reachability: for a lazy boundary, check all synchronous root-to-target paths, alternate importers and cycles, including a target that is itself a root. Record which paths the proposed boundary severs and which stay reachable. Verify async and erased type-only imports against source.
Source checks: inspect import triggers, mount-time preloading, module side effects and shared routes. Record the conditions under which an async import executes. The graph establishes indexed reachability; an after snapshot verifies emitted outputs and attribution changes.
Method: record the chosen method, its parameters and why it fits the candidate.

For lazy interaction features, duplicate packages, server-rendered display work or other attributed assets, read the matching section in Fix patterns before proposing an edit.

Done: the paired pass and its target dispositions are recorded, or the narrow-scope skip reason or blocker is explicit. Every candidate has a completed checklist, exact source/importer, proposed edit and named behavior checks. Label heuristics as heuristics and qualify conclusions affected by evidence gaps; the report step completes audit mode.

在提出编辑前，为每个候选项记录以下内容。不适用的项目应注明原因；缺失的证据应明确标为缺口。

范围（Scope）： 指定路由、snapshot、渲染条件、客户端/服务端输出类别、准确目标身份和指标。对于可达性结论，标识每个选定的客户端根节点，包括适用的客户端引用。
覆盖范围（Coverage）： 概括相关的不受支持输出和未解析引用，并说明现有原因及其对结论的影响。无法确定完整性时，将结论限定在已知子图内。
归因（Attribution）： 每个选定的输出贡献只计数一次。记录重复记录的处理方式，并区分源路径与模块身份；说明用于求解器权重的任何映射，并将未知权重保留为证据缺口。
可达性（Reachability）： 对于 lazy boundary，检查从根节点到目标的所有同步路径、其他 importer 和环，包括目标本身也是根节点的情况。记录拟议边界会切断哪些路径，以及哪些路径仍可达。根据源代码验证 async import 和被擦除的 type-only import。
源代码检查（Source checks）： 检查 import 触发条件、挂载时预加载、模块副作用和共享路由。记录 async import 执行的条件。图建立的是基于索引的可达性；after snapshot 用于验证生成的输出和归因变化。
方法（Method）： 记录所选方法、参数及其适用于该候选项的原因。

对于延迟交互功能、重复 package、服务端渲染的显示工作或其他已归因资产，在提出编辑前阅读 Fix patterns 中对应章节。

完成： 已记录配对流程及其目标处置结果，或已明确说明窄范围审计的跳过原因或阻塞项。每个候选项都有已完成的检查清单、准确的源文件/importer、拟议编辑和明确的行为检查。将启发式判断明确标为启发式，并限定受证据缺口影响的结论；报告步骤即完成 audit 模式。

5. Verify one change — fix mode only

5. 验证一项更改——仅限 fix 模式

Make one small, cohesive change. Capture/export an after snapshot with a new name and compare the same route, output class and metric with the baseline. Run relevant behavior tests and type-check; use

next-dev-loop

when verifying the edit in the running app.

Done: retain the change only when the scoped metric improves and the intended behavior passes its checks. Revert a change that fails either condition. If checks are blocked, report the unverified edit and blocker rather than accepting it. Record the accepted after snapshot as the next baseline before another edit.

进行一个小而内聚的更改。使用新名称捕获并导出 after snapshot，并将同一路由、输出类别和指标与基线比较。运行相关行为测试和类型检查；在运行中的应用中验证编辑时使用

next-dev-loop

。

完成： 仅当范围内的指标有所改善且预期行为通过检查时，才保留该更改。任一条件未通过时，回退更改。如果检查受阻，应报告未经验证的编辑和阻塞项，而不是接受该更改。将已接受的 after snapshot 记录为下一次编辑前的基线。

6. Report and stop

6. 报告并停止

Audit reports candidates; fix reports accepted edits and any reverted or unverified attempts. Include snapshot names, scoped attribution/deltas, exact source/importer, behavior-check results and blockers. For a graph cut, include its route/render conditions, roots/target and unknowns. Distinguish source facts, build evidence, heuristics and separately observed runtime facts.

Done: every scoped candidate or attempted edit is accounted for, with evidence or a stated gap.

audit 模式报告候选项；fix 模式报告已接受的编辑，以及已回退或未经验证的尝试。包含 snapshot 名称、范围内的归因/差值、准确的源文件/importer、行为检查结果和阻塞项。对于图割，包含其路由/渲染条件、根节点/目标和未知项。区分源代码事实、构建证据、启发式判断和单独观察到的运行时事实。

完成： 每个范围内的候选项或已尝试的编辑都已得到交代，并附有证据或明确说明缺口。