Perfonext Build MCP

perfonext-build-mcp

分析 Next.js 构建产物，找出体积较大的路由、共享分块和包体积增长。

perfonext-build-mcp 是一个 Model Context Protocol（MCP）服务，可为 GitHub Copilot、Claude Desktop、 Claude Code 和其他 MCP 客户端提供结构化的包分析，助力 Next.js 性能优化。它会加载 .next 构建产物，并将其转换为路由体积排名、共享分块与重复内容分析结果，以及按严重程度排序的修复建议—— 为 Agent 提供可供推理的依据，而不必检查原始 .next 清单。

快速开始

perfonext-build-mcp 是标准的 MCP stdio 服务，因此可与任何兼容 MCP 的客户端配合使用 （VS Code 中的 GitHub Copilot、Claude Desktop、Claude Code、Cursor 等）。使用 npx 直接运行：

npx -y @perfonext/build-mcp

也可以全局安装：

npm install -g @perfonext/build-mcp

安装后，可执行命令仍为 perfonext-build-mcp。

VS Code

将服务添加到 .vscode/mcp.json（工作区 MCP 配置文件）：

{
  "servers": {
    "perfonext-build": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perfonext/build-mcp"]
    }
  }
}

重新加载 VS Code 窗口，然后运行 MCP: List Servers 启动服务，或在出现信任提示时接受。

Claude Desktop

将服务添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "perfonext-build": {
      "command": "npx",
      "args": ["-y", "@perfonext/build-mcp"]
    }
  }
}

重启 Claude Desktop 以加载新服务。

Claude Code

使用 CLI 添加服务：

claude mcp add perfonext-build -- npx -y @perfonext/build-mcp

也可以直接添加到 .mcp.json：

{
  "mcpServers": {
    "perfonext-build": {
      "command": "npx",
      "args": ["-y", "@perfonext/build-mcp"]
    }
  }
}

其他 MCP 客户端

任何支持 stdio MCP 服务的客户端都可以运行同一组命令和参数： command: npx、args: ["-y", "@perfonext/build-mcp"]。请查阅客户端文档，了解 MCP 服务配置文件的位置。

对于本地构建的代码库，可在上述任意配置中将 command/args 指向 node 和代码库的 dist/index.js。

然后向助手提问："加载 ./.next 中的 Next.js 构建产物，并显示体积最大的路由。"

故障排除

在使用 nvm 的 macOS 上出现 spawn npx ENOENT / spawn node ENOENT

如果服务因 spawn npx ENOENT（或 spawn node ENOENT）而无法启动，可能是因为你的编辑器或应用 从 Dock/Finder 启动，无法访问 nvm。macOS 上的 GUI 应用不会加载 shell 配置文件 （.zshrc/.bashrc），因此通过 nvm 安装的 npx/node 不在 PATH 中。此问题适用于 VS Code、 Claude Desktop 以及 macOS 上的其他 GUI MCP 客户端。

为 MCP 配置指定 npx 的绝对路径，并设置包含同一 Node bin 目录的 PATH （dirname $(which npx)），即可解决：

{
  "command": "/Users/YOU/.nvm/versions/node/v<version>/bin/npx",
  "args": ["-y", "@perfonext/build-mcp"],
  "env": {
    "PATH": "/Users/YOU/.nvm/versions/node/v<version>/bin:/usr/bin:/bin"
  }
}

将上述 command/args/env 字段合并到客户端的服务条目中（例如 VS Code 的 servers 或 Claude Desktop/Code 的 mcpServers）。

功能

• 从 .next 目录加载 Next.js 构建产物
• 按生成的包体积对面向用户的路由进行排名
• 找出影响多个路由的最大共享分块
• 比较两次构建，并说明哪些路由和分块导致包体积增长，同时提供 按严重程度排序且有证据支持的修复建议
• 即使 Next.js 使用内容哈希为文件名生成指纹，也能跨构建匹配分块
• 在收集到可选的 webpack stats 文件时，追踪某个模块或 npm 包为何被打包（导入链入口 → 模块）
• 找出跨分块重复出现的 npm 包，并说明共享分块中哪些内容占比最高
• 将以上分析汇总为按严重程度排序、有证据支持且对应具体 Next.js 操作的优化建议
• 将已加载的构建快照保存在内存中，方便 MCP 客户端查看，无需重复读取同一构建

工具

工具	描述
load_build_stats	解析 Next.js .next 目录，并将构建快照载入内存
get_largest_routes	按总输出分块字节数，对面向用户的最大路由进行排序
get_shared_chunks	按大小对共享分块进行排序，并显示依赖这些分块的路由
compare_builds	比较基线构建和当前构建的快照，显示哪些路由和分块变大或变小
explain_growth	按严重程度对导致两个构建之间包体积增长的路由和分块进行排序，并提供基于证据的修复建议
how_to_collect_stats	返回生成 .next/stats.json 的操作步骤（手动）或行动计划（自动）
load_webpack_stats	解析 .next/stats.json 并将其关联到已加载的构建；执行 trace_import 前必须先调用
trace_import	沿着模块的导入链追溯至入口，说明模块或 npm 包为何被打包
find_duplicates	按浪费的字节数对代码被输出到多个分块中的 npm 包进行排序
explain_shared_chunks	显示由多个路由加载的共享分块中，哪些包和应用代码占比最大
suggest_optimizations	汇总路由、分块和 webpack-stats 证据，按严重程度提供基于证据的修复建议

输出始终为机器可读格式，并包含原始字节数，因此 MCP 客户端可以解释回归、确定修复优先级，并建议针对依赖或导入的具体后续操作。

每项 suggest_optimizations 发现都以 emittedBytes 标注大小，即实际磁盘上的分块字节数，因此不同类型的建议可以按同一标准排序。未压缩的 webpack 模块大小仅在明确以此命名的字段中出现（moduleSizeBytes、shareOfChunkModuleBytes）。

由于 Next.js 会对输出文件名进行内容哈希处理（framework-<hash>.js，而 CSS 文件名完全由哈希组成），compare_builds 和 explain_growth 会根据经过哈希规范化的标识来匹配不同构建中的分块。这样可以避免将仅重新生成哈希、内容未变的分块误报为删除后重建，同时仍会标记真正新增的分块。

输入

核心工具读取开发者运行 next build 后已有的构建产物：

• .next/build-manifest.json
• .next/prerender-manifest.json（如果存在）
• .next/app-build-manifest.json（如果存在）
• .next/app-path-routes-manifest.json（如果存在）——将 App Router 清单键（/gallery/page）映射到预渲染清单所使用的真实路径（/gallery），因此路由的 type、isPrerendered 和 prerenderBlockedReason 会从构建中读取，而不是根据路径猜测
• 可选的已捕获 next build 输出文本，用于推导构建时长

导入级别的归因（trace_import、find_duplicates、explain_shared_chunks）以及 suggest_optimizations 中包含 stats 数据的建议，还需要 .next/stats.json 中的 webpack 模块 stats 文件。标准的 next build 不会生成该文件；how_to_collect_stats 会返回生成该文件的操作步骤。上述清单工具不会读取此文件，因此无论是否有该文件都能正常工作。

深度捆绑归因（可选）

清单工具无需任何设置即可使用。若要回答“为什么这个软件包会被捆绑？”，请先收集 webpack stats 文件：

1. 调用 how_to_collect_stats({ method: 'manual' | 'automatic' }) 并按返回的步骤操作 — 该步骤会添加 webpack-stats-plugin 和 cross-env，在 ANALYZE=true && !isServer 条件下启用 next.config 钩子，并使用 cross-env ANALYZE=true next build --webpack 重新构建。Turbopack 构建不会生成 .next/stats.json。
2. 调用 load_build_stats({ buildDir }) 获取 buildId。
3. 调用 load_webpack_stats({ buildId }) 解析生成的 .next/stats.json。
4. 调用 trace_import({ buildId, moduleName }) 查看引入某个模块的导入链。
5. 调用 find_duplicates({ buildId }) 查找被捆绑到多个代码块中的软件包，并调用 explain_shared_chunks({ buildId }) 查看被多个路由加载的代码块主要由什么组成。
6. 调用 suggest_optimizations({ buildId }) 获取按严重程度排序、有证据支持的建议。 该工具仅依赖清单即可运行；加载 stats 后，还会补充去重、共享代码块和软件包导入方面的发现。代码拆分建议针对 Next.js 框架路由（/404、/500、/_error、/_app、/_document）进行了调整 — 对这些路由，建议通过精简导入来缩减体积，而非使用 next/dynamic 拆分，因为 next/dynamic 不适用于这些路由。

如果应用使用 Turbopack 构建，就不会有 webpack 模块图，因此 how_to_collect_stats 会说明这一点，并引导你使用仅依赖清单的工具。未加载 stats 文件时，归因工具仍可正常运行，并会提供线索 — 这不会导致错误。

示例提示词

• “加载 ./.next 中的 Next.js 构建，并显示体积最大的路由。”
• “此构建中，哪些共享代码块影响的路由最多？”
• “概述构建体积，并告诉我哪些路由打包了最多的 JavaScript。”
• “比较基准版本和当前 .next 构建，显示体积增长最多的路由或共享代码块。”
• “说明基准版本和当前 .next 构建之间有哪些增长，以及我应该优先修复什么。”
• “设置 webpack stats 收集，以便我查看某个软件包为何会被捆绑。”
• “为什么我的捆绑包中有 axios？追踪它的导入链。”
• “哪些 npm 软件包在多个代码块中重复出现？浪费了多少字节？”
• “我的共享代码块主要由什么组成？”
• “针对这个构建，建议影响最大的捆绑优化方案。”

相关 Perfonext 工具

• perfonext-profiler-mcp — 为 Next.js 服务进行 CPU 性能分析（V8/Chrome）
• perfonext-render-mcp — 分析 Next.js 应用的 React 渲染

开发

npm install
npm run build
npm test

用于本地验证的示例夹具位于 tests/fixtures/ 下。

许可证

MIT