next-bundle-optimizer

包优化器

1. 确定范围

默认分析整个应用，涵盖所有路由和共享客户端依赖项。仅当用户指定路由、依赖项、功能或其他子集时才缩小范围。选择 审计 或 修复 模式。默认采用审计模式：生成分析器产物并报告候选项，同时保持应用源代码、依赖项和锁文件不变。修复模式需要用户明确要求修改应用。更改可见行为、时序、兼容性或信任边界前，请先询问。对于路由的静态 App Shell，请使用 next-cache-components-optimizer；如果不可用，请先安装（npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer）。对于导航预取工作，请使用 next-partial-prefetching-optimizer；如果不可用，请先安装（npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-partial-prefetching-optimizer）。

完成标准： 已记录整个应用或用户指定的范围、模式和预期行为。请求捕获或导出数据属于审计模式，并不代表获准修复。

2. 捕获并导出基线

在应用目录中使用其包管理器运行。阅读 next analyze --help，了解捕获选项；阅读已安装 CLI 中的 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' | gzip > /tmp/analyze-app-before.jsonl.gz

--output 会构建并保存二进制/UI 产物，但不会启动服务。next analyze export 会读取已保存的快照，而不会进行构建；标准输出中每行是一条带类型的 JSON 记录，错误信息则输出到标准错误。对整个应用进行分析时，省略 --route；用户指定路由时，添加该选项。路由筛选器会保留整个应用的模块图，因此请在下一步中限定范围。

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

完成标准： 已确认所选捕获，导出成功，并记录基线文件、快照名称和分析范围。在处理压缩文件前检查整个流程的退出状态：pipefail 可防止 gzip 掩盖导出失败。导出会逐个路由进行验证，因此即使 gzip -t 接受了归档文件，失败时仍可能留下部分归档。导出或 gzip 失败时，请丢弃输出。

3. 解读证据

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

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

阅读其中的描述，了解记录含义、连接、归因和覆盖范围。使用 gzip -dc /tmp/analyze-app-before.jsonl.gz 流式解压，并将内容传入逐行分析脚本，而不是将整个转储加载到上下文中。使用 schema 解读范围内每条路由的客户端／服务端贡献，并选择指标。

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

4. 说明候选方案

检查项目的实际源码和确切的导入方。按归因大小、重复情况、可能的运行时成本、交互前是否需要以及正确性风险，对整个应用或用户指定范围内的客户端输出贡献进行排序。

社区 → 最小割流程

对于旨在跨多个功能或较长贡献者列表寻找机会的广泛审计，请在初步排序后执行社区检测 → 目标选择 → 有向最小割 → 源码验证。在构建图或运行求解器之前，请先阅读图方法。

1. 根据范围内的客户端输出归因对检测到的社区排序，并检查其入站导入方。
2. 选择较大的社区，或其中可能等到交互后再加载的可选功能区域。记录在该路由的渲染条件下，各选定区域为何是可选的。
3. 从已验证的客户端根节点对这些目标运行有向最小割，找出一小组可能将其分离的导入方变更。
4. 根据源码和行为约束验证割边；将每个已调查的目标列为候选方案、已否决的割或证据缺口。

对于针对某个明确依赖项或功能的狭窄审计，如果直接分析导入方已能完整说明相关路径和拟议边界，则使用这种方法；同时记录为何成对流程无法发现有用的新目标。如果图证据或工具阻碍了该流程，则记录阻碍，并据此限制结论。

图证据清单

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

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

对于惰性交互功能、重复软件包、服务端渲染展示工作或其他已归因资源，提出编辑前请阅读修复模式中的对应章节。

**完成条件：**已记录配对检查及其目标处置，或明确说明限定范围内跳过的原因或阻碍因素。每个候选项都已填写完整清单，并记录确切的源代码／导入者、拟议编辑和具名行为检查。将启发式方法标记为启发式；若证据存在缺口，应限定受其影响的结论；报告步骤完成 audit 模式。

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

进行一项小而连贯的更改。使用新名称捕获／导出更改后的快照，并与基线比较相同的分析范围、输出类别和指标。对于整应用分析，请考虑所有路由的变化，包括共享依赖项。运行相关行为测试和类型检查；在运行中的应用里验证编辑时，请使用next-dev-loop，若该工具不可用，请先安装（npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop）。

**完成条件：**只有在限定范围内的指标有所改善，且预期行为通过检查时，才保留更改。若更改未满足任一条件，则还原该更改。若检查受阻，应报告尚未验证的编辑和阻碍因素，而不是接受该编辑。在进行下一项编辑前，将已接受的更改后快照记录为新的基线。

6. 报告并停止

audit 报告候选项；fix 报告已接受的编辑，以及任何已还原或尚未验证的尝试。包括快照名称、限定范围内的归因／变化量、确切的源代码／导入者、行为检查结果和阻碍因素。对于图切，列出其路由／渲染条件、根节点／目标和未知项。区分源代码事实、构建证据、启发式方法和单独观察到的运行时事实。

**完成条件：**每个限定范围内的候选项或尝试过的编辑都已说明，并附有证据或明确指出缺口。