nextjs-bundle-optimizer

Next.js 包体积与构建时优化器

面向 Next.js 16 应用的、以数据驱动的优化循环。该技能通过协调 next experimental-analyze、构建、类型检查和测试，每次只做一项更改，从而实现可验证的优化。

适用时机

在以下情况下使用此技能：

• 用户希望缩减 Next.js 16 应用的包体积、First Load JS 或路由包体积。
• 生产构建速度缓慢，用户希望诊断并解决瓶颈。
• 用户分享了分析器输出、树状图截图，或询问“为什么 <X> 这么大？”
• 添加了新的依赖，导致包体积增大，用户想了解原因并撤销相关更改。
• 用户希望设定性能预算并逐步加以执行。

为什么要迭代（而不是“一次性应用所有优化”）

包体积优化很容易踩坑。例如：

• 将“仅限客户端”的依赖移到 next/dynamic 后面，可能会破坏依赖它在首次绘制时存在的 SSR 使用方。
• 将 experimental.optimizePackageImports 用于不合适的包，可能会错误解析子路径导出。
• 激进的 modularizeImports 正则重写可能会匹配到非预期模块。
• 收紧 polyfill 目标范围，可能会导致生产环境中的旧款移动浏览器无法正常工作。

唯一可靠的方法是：每次只做一项更改，测量、验证，然后提交（或撤销）。此技能通过脚本强制执行这一流程。

前置条件

• Next.js 16+ 项目（此技能会从 package.json 中自动检测）。
• git（工作流使用提交作为检查点，并通过还原来回滚）。
• jq 已添加到 PATH 中（分析和比较脚本会用到）。
• 开始前，工作树必须干净（验证步骤会使用 git status 确认）。
• 对于仍使用 Next.js 15 或更早版本且处于 webpack 模式的项目：此技能会检测到这一点，并改用 @next/bundle-analyzer，而非 experimental-analyze。请参阅 gotchas.md。

设置

首次使用时，运行：

bash scripts/baseline.sh --setup

此操作会交互式配置 config.json。如果 config.json 中已有值，脚本会直接使用这些值并跳过提示。

工作流概览

┌── 1. baseline ──┐   Clean build, snapshot bundles + timing → baselines/{timestamp}/
│                 │
│   2. analyze ───┤   Run `next experimental-analyze --output`, extract top offenders
│                 │
│   3. diagnose ──┤   Map each offender to a recipe in references/optimizations.md
│                 │
│   ── apply ─────┤   User (or agent) applies ONE recipe. Skill helps draft the change.
│                 │
│   4. measure ───┤   Re-build, re-analyze, save to iterations/{n}/
│                 │
│   5. compare ───┤   Diff vs baseline; flag regressions; print delta table
│                 │
│   6. verify ────┤   Build + tsc + tests + no overall regression. Hard PASS/FAIL.
│                 │
│   commit OR ────┘   `git commit` (PASS+improvement) or `git revert` (FAIL/no win)
│   revert
│
└── loop back to step 2 with new baseline if you want a fresh measurement point.

请阅读 references/workflow.md，了解包含错误处理、回滚流程以及各脚本输出示例的详细循环。

快速参考

脚本（从 Next.js 应用根目录运行）

脚本	用途	输出
scripts/baseline.sh	建立参考点	baselines/{ts}/{bundle,timing,manifest}.json
scripts/analyze.sh	运行分析器，解析影响最大的项目	iterations/{n}/findings.json
scripts/diagnose.sh [findings.json]	将发现映射到优化方案	stdout：按优先级排列的优化方案列表
scripts/measure.sh	更改后重新测量	iterations/{n}/{bundle,timing}.json
scripts/compare.sh [baseline] [current]	对比快照	stdout：差异表；发生回归时退出码为 1
scripts/verify.sh	完整验证	退出码为 0 表示可安全提交，退出码为 1 表示应撤销

优化方案

references/optimizations.md 按分析器信号整理了优化方案：

包体积

• 桶文件导入造成的膨胀 → experimental.optimizePackageImports（webpack）／Turbopack 中自动处理
• 沉重的客户端库被引入每个路由 → next/dynamic({ ssr: false })
• 从客户端组件导入仅供服务端使用的库 → 移到服务端组件
• 依赖版本重复 → 通过 overrides／resolutions 去重
• polyfill 膨胀 → 收紧 browserslist
• 图标库按单个图标导入

构建时间

• 启用 experimental.turbopackFileSystemCacheForBuild
• 缩小 transpilePackages 的范围（过度使用会大幅延长编译时间）
• 在 CI 中将 tsc --noEmit 与 next build 分开
• 使用 NEXT_TURBOPACK_TRACING=1 找出单文件瓶颈

每个优化方案都会说明：信号 → 修复方法 → 预期影响 → 验证步骤。

易踩问题

请参阅 gotchas.md，了解已汇总的常见失败点。初始内容涵盖最常见的 Next.js 16 陷阱：

• next build 不再输出 First Load JS — 不要在构建输出中搜索它。
• optimizePackageImports 在 Turbopack（16 中的默认选项）下不起作用 — Turbopack 会自动优化。
• 比较构建时间时需要控制缓存状态 — 要么删除 .next/（冷缓存），要么预热缓存（热缓存）。

相关技能

• vercel:nextjs — Next.js App Router 通用指南；应用配方时，可参考它来制定重构决策。
• vercel:turbopack — 用于排查本技能未涵盖的构建时问题。
• vercel:next-cache-components — 当配方涉及缓存边界时使用。