next-browser-initial-load-optimizer

浏览器初始加载优化器

1. 确定范围

选择一个路由，并选择审计或修复模式。默认采用审计模式：生成分析器产物并报告候选项，同时保持应用源码、依赖项和锁文件不变。修复模式需要明确要求修改应用。在更改可见行为、时序、兼容性或信任边界之前，请先询问。对于路由的静态 App Shell，请使用 next-cache-components-optimizer；对于导航预取工作，请使用 next-partial-prefetching-optimizer。

**完成标准：**已记录路由、模式和预期行为。要求捕获或导出数据属于审计模式，并不代表允许修复。

2. 捕获并导出基线

在应用目录中使用其包管理器运行。阅读已安装 CLI 中的 next analyze --help，了解捕获选项；阅读 next analyze export --help，了解重放选项。重用选定的已保存快照，或先用一个醒目的名称捕获；然后以默认压缩级别通过 gzip 导出。将前后两份 .jsonl.gz 文件分开保存。

**沙盒要求：**如果 Agent 的沙盒阻止绑定 TCP 端口（例如 Codex 的沙盒），则必须在沙盒外运行 next analyze --output 捕获。即使 --output 不会启动分析器 UI，也不要在该沙盒内尝试捕获。

在 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 会构建并保存二进制/UI 产物，但不会启动服务。next analyze export 会读取已保存的快照而不进行构建；标准输出每行包含一条带类型的 JSON 记录，错误信息写入标准错误。路由筛选器会保留整个应用的模块图，因此请在下一步中限定范围。

对于自定义 distDir，请使用 --dist-dir <configured-directory>（相对路径或绝对路径）进行重放：捕获时会加载应用配置，重放时则不会。--snapshot <name> 用于选择保留的名称；省略时会选择最新快照。若省略名称，捕获会生成唯一的时间戳名称；若重用显式名称，则会替换现有捕获。请使用不同的前后名称，包括带空格的名称，以保留两份基线。若要进行交互式探索，请在不使用 --output 的情况下捕获，以启动 UI；next build --analyze 也会生成可重放的数据。

**完成标准：**已确定所选捕获，导出成功，并记录基线文件、快照名称和所选路由。在处理压缩文件之前，请检查整个流水线的退出状态：pipefail 可防止 gzip 掩盖导出失败。导出每次只验证一个路由，因此即使 gzip -t 验证通过，失败时仍可能留下不完整的归档。如果导出或 gzip 失败，请丢弃输出。

3. 解读证据

使用应用已安装的 Next.js，通过其 Node 启动器解析架构：

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

阅读架构说明，了解记录含义、关联、归因和覆盖范围。使用 gzip -dc /tmp/analyze-dashboard-before.jsonl.gz 流式解压，并将内容传给逐行分析脚本，而不是把整个转储加载到上下文中。使用架构解读所选路由的客户端/服务端贡献，并选择指标。

完成标准：已确定基线中归因到路由的客户端/服务端贡献及指标。请将其视为构建证据：关于观察到的浏览器请求、时序或传输节省的说法，需要单独的证据支持。

4. 说明候选项

检查实际项目源码和具体导入方。从指定路由入手，或按归因大小、重复情况、可能的运行时成本、交互前的必要性和正确性风险，对限定范围内的客户端输出贡献进行排序。

社区 → 最小割流程

对于要广泛审查多个功能或大量贡献者，并寻找优化机会的情况，请在初步排名后运行 社区检测 → 目标选择 → 有向最小割 → 源码验证。在构建图或运行求解器之前，请阅读 图方法。

1. 按范围内客户端输出归因对检测到的社区排序，并检查其入向导入者。
2. 选择大型社区，或其中可选的功能区域作为目标，这些目标应当可以合理地延后到交互时再加载。记录每个选定区域在该路由渲染条件下为何属于可选内容。
3. 从已验证的客户端根节点到这些目标运行有向最小割，找出能够将它们分离的少量导入者变更。
4. 根据源码和行为约束验证割边；将每个已调查目标记录为候选项、已否决的割或证据缺口。

对于针对特定依赖项或功能的狭窄审查，如果直接分析导入者足以完整说明相关路径和拟议边界，则使用这种方法；并记录为何配套流程无法发现有用目标。如果图证据或工具导致流程受阻，请记录阻碍因素，并据此限制结论范围。

图证据检查清单

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

• **范围：**注明路由、快照、渲染条件、客户端／服务端输出类别、精确目标标识和指标。对于可达性结论，列出每个选定的客户端根节点，包括适用的客户端引用。
• **覆盖范围：**概述相关的未支持输出和未解析引用，并记录已有原因及其对结论的影响。如果无法确定是否完整覆盖，请将结论限定在已知子图内。
• **归因：**每项选定的输出贡献只计一次。记录对重复记录的处理方式，并区分源码路径与模块标识；说明用于求解器权重的任何映射，并将未知权重保留为证据缺口。
• 可达性：对于延迟加载边界，检查所有从根节点到目标的同步路径、替代导入者和循环，包括目标本身就是根节点的情况。记录拟议边界会切断哪些路径，以及哪些路径仍可达。对照源码验证异步导入和已擦除的纯类型导入。
• **源码检查：**检查导入触发条件、挂载时预加载、模块副作用和共享路由。记录异步导入执行的条件。图只能证明已索引的可达性；之后的快照用于验证生成的输出和归因变化。
• **方法：**记录所选方法、参数及其适用于该候选项的原因。

对于延迟加载的交互功能、重复包、服务端渲染的展示工作或其他已归因资源，提出编辑建议前，请阅读 修复模式 中对应的部分。

**完成标准：**已记录配套流程及其目标处置结果，或明确说明跳过狭窄范围审查的原因或阻碍因素。每个候选项均已完成检查清单，并注明确切源码／导入者、拟议编辑和具体行为检查。启发式判断应标注为启发式；受证据缺口影响的结论应注明限定条件；报告步骤完成后，审计模式即告完成。

5. 验证一项变更 — 仅限修复模式

进行一项小型、整体连贯的变更。使用新名称捕获／导出变更后快照，并针对相同路由、输出类别和指标与基线进行比较。运行相关行为测试和类型检查；在运行中的应用内验证编辑时，请使用 next-dev-loop。

**完成标准：**只有当范围内指标有所改善，且预期行为通过检查时，才保留变更。任何一项不满足时都应撤销变更。如果检查受阻，请报告尚未验证的编辑及阻碍因素，不要直接接受该变更。将已接受的变更后快照记录为下一次编辑前的新基线。

6. 报告并停止

Audit 报告候选项；fix 报告已接受的编辑，以及任何已回滚或未经验证的尝试。包括快照名称、范围内的归因/差异、确切的源文件/导入方、行为检查结果和阻碍因素。对于图切，说明其路由/渲染条件、根节点/目标和未知项。区分源代码事实、构建证据、启发式判断和单独观测到的运行时事实。

**完成标准：**每个范围内的候选项或尝试过的编辑都有交代，并附上证据或说明存在的缺口。