Perfonext Profiler MCP

// Input
{ "scenario": "next-server" } // or "script"; defaults to "next-server"

// Output
{
  "scenario": "next-server",
  "summary": "Profile a production Next.js server while it handles a single request. ...",
  "command": "node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start",
  "steps": [ "...", "load_profile({ filePath: \"./.perf-profiles/<file>.cpuprofile\" })" ],
  "outputDir": "./.perf-profiles",
  "nextStep": "After stopping the server, call load_profile with the .cpuprofile ..."
}

next-server 会在生产版 Next.js 服务处理单个请求时对其进行性能分析。如果 next start 提示不支持 standalone 输出，请使用 script 场景，并指定 .next/standalone/server.js。script 会对该 standalone 服务（或其他 Node 入口）进行性能分析。场景仅限一个路由和一次请求。Node 会在输出目录中为每个进程／工作线程写入一个 .cpuprofile 文件。Next 服务命令使用 Node CLI 标志（而非 NODE_OPTIONS），因此在 Unix 和 Windows 上都相同。

read_source_context 详情

// Input
{ "profileId": "<id>", "functionName": "myFn", "contextLines": 10 }

// Output (per line)
{
  "lineNumber": 42,
  "content": "  for (let i = 0; i < items.length; i++) {",
  "ticks": 18,      // V8 samples that landed on this line
  "isHot": true     // true when ticks >= 50% of peak ticks for this function
}

返回的代码窗口会覆盖函数实际的热点代码行，而不只是围绕函数声明的固定范围——函数的真正瓶颈往往远在 function 行之后。contextLines（默认值为 10）用于设置函数声明和热点代码行两侧的最小填充行数；如果仍有采样点落在返回窗口之外，顶层结果会包含 hiddenTicks（计数）和 warning，提示你使用更大的 contextLines 重试。使用 includeSource: true 调用时，explain_function 也接受 contextLines。

只能读取当前工作目录中的文件。file:// URL 和绝对路径均受支持；http://、node: 内置模块以及项目根目录之外的路径则会被拒绝。

suggest_optimizations 详情

// Input
{ "profileId": "<id>", "limit": 5 }

// Output (per function)
{
  "function": "processData",
  "file": "file:///app/src/processor.js",
  "line": 10,
  "selfPercent": "18.2%",
  "patterns": [
    {
      "pattern": "high-fan-in",
      "detail": "Called from 6 distinct call sites (e.g. renderRow, buildTree, …)",
      "suggestion": "This function is a shared hot path. Ensure it is well-optimised and monomorphic …"
    },
    {
      "pattern": "hot-caller",
      "detail": "84% of calls come from \"renderRow\"",
      "suggestion": "Focus optimisation effort on \"renderRow\" rather than this function …"
    }
  ],
  "topSuggestion": "This function is a shared hot path …"
}

检测到的模式（同一个函数可能触发多个模式）：

在排序之前，出现在多个调用点的函数会自动合并，因此同一个逻辑函数只会报告一次。

get_package_costs 详情

// Input
{ "profileId": "<id>", "limit": 10 }

// Output (per package)
{
  "rank": 1,
  "package": "lodash",
  "selfTime": "42.3ms",
  "selfPercent": "14.1%",
  "totalTimeIncludingCallbacks": "58.0ms",
  "totalPercentIncludingCallbacks": "19.3%",
  "topFunctions": [
    { "function": "chunk", "file": "lodash/chunk.js", "line": 41, "selfTime": "28.0ms", "selfPercent": "9.3%" }
  ]
}

selfTime 是在包自身代码中耗费的时间。totalTimeIncludingCallbacks 还会统计该包调用的所有内容——包括传回给它的自定义回调——因此可能会高于移除该包实际能节省的时间。

Scoped 包（如 @babel/core、@next/env 等）会被正确处理。用户代码和原生内置模块（路径中没有 node_modules）会被排除。

生成 CPU 配置文件

让 Copilot 调用 how_to_collect 获取可直接运行的方案，或手动生成：

Next.js 生产服务（对单个请求进行性能分析）：

node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start
# hit the route once, then stop the process so it can exit and write the profile

如果 next start 提示不支持 standalone 输出：

node --cpu-prof --cpu-prof-dir=./.perf-profiles .next/standalone/server.js

Chrome DevTools：

1. 打开 DevTools 并进入 Performance 选项卡。
2. 录制你想检查的场景。
3. 停止录制并将结果保存为 .cpuprofile 导出文件。