rspack-tracing

Rspack 跟踪与性能分析

何时使用此技能

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

1. 诊断 Rspack 构建缓慢的原因。
2. 了解哪些插件或加载器耗时最长。
3. 分析用户提供的 Rspack 跟踪文件。
4. 指导用户采集性能配置文件。

工作流

1. 采集跟踪文件

首先，请用户在启用跟踪功能的情况下运行构建。

# Set environment variables for logging to a file
RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json pnpm build

这会在带有时间戳的目录中生成跟踪文件，例如 .rspack-profile-{timestamp}-{pid}/trace.json。

有关配置的更多详情，请参阅 references/tracing-guide.md。

2. 快速诊断崩溃/错误

如果用户想要确定崩溃或错误发生在哪个阶段，请使用 tail 快速查看最后的事件，无需运行完整分析：

# Navigate to the generated profile directory
cd .rspack-profile-*/

# View the last 20 events to see where the build failed
tail -n 20 trace.json

最后的事件会显示构建停止处的 span 名称和目标，有助于快速定位问题阶段、插件或加载器。

3. 完整性能分析

如需进行详细的性能分析（而不仅是诊断崩溃），请询问用户是否要对生成的跟踪文件运行随附的 scripts/analyze_trace.mjs。如果用户同意，请相对于 Skill 根目录解析该脚本，同时将工作目录保留在用户的项目中，然后运行：

# Navigate to the generated profile directory
cd .rspack-profile-*/

# Run the analysis script
node "<skill-root>/scripts/analyze_trace.mjs" trace.json

4. 解读结果

使用脚本的输出识别瓶颈。 请参阅 references/bottlenecks.md，了解如何将 span 名称对应到可执行的修复方案。

5. 定位缓慢的插件

根据分析脚本给出的“最耗时的 Hook”：

1. 识别 Hook：记下 Hook 名称（例如，hook:CompilationOptimizeChunks）。
2. 检查配置：读取 rspack.config.js 或 rsbuild.config.ts。
3. 将 Hook 对应到插件：查找接入该特定 Hook 的插件及其源代码。
4. 输出：输出可疑插件源代码所在的路径、行号和列号。

常见场景与快速修复

• 瓶颈参考：将 span 对应到相关概念。
• 跟踪指南：RSPACK_PROFILE 的详细用法。