rspack-debugging

Rspack 调试

概述

本 Skill 将指导你如何捕获 Rspack（基于 Rust）的底层崩溃状态。使用 LLDB 调试器和包含调试符号的 Rspack 包，我们可以获取详细的堆栈回溯，这对定位问题至关重要。本指南侧重于非交互式自动调试，以便轻松捕获堆栈回溯。

准备工作

开始之前，请确保你的环境满足以下要求。

1. 安装 LLDB：你必须安装 LLDB 调试器。

   • macOS：运行 xcode-select --install
   • Linux：安装 lldb 包（例如，apt-get install lldb）
   • 详细指南：references/lldb.md

2. 替换调试包： @rspack/core 等生产环境包已剥离调试符号。要查看有用的堆栈信息，必须将它们替换为 @rspack-debug/* 系列包。

   自动替换脚本：

   在 Skill 根目录下解析捆绑的 scripts/setup_debug_deps.cjs 路径，同时将工作目录保留在用户的 项目中，然后运行：

   node "<skill-root>/scripts/setup_debug_deps.cjs"
   

   运行上述脚本会自动在 package.json 中添加 pnpm.overrides 配置，将 Rspack 包指向对应的 Debug 版本。之后，请务必运行 pnpm install 更新依赖。

调试工作流

确定你的具体场景，并按照对应的指南操作。

详细指南

详细指南

指南 A：HMR 期间崩溃

场景：DevServer HMR 期间稳定复现崩溃／死锁。 阅读指南：references/guide_a_hmr_crash.md

指南 B：构建期间崩溃

场景：构建期间稳定复现崩溃／死锁（或频繁发生的不稳定构建崩溃）。 阅读指南：references/guide_b_build_crash.md

指南 C：附加到卡住的进程

场景：构建期间出现不稳定的死锁（随机发生）。 阅读指南：references/guide_c_attach_to_stuck_process.md

指南 D：核心转储分析（开发）

场景：DevServer HMR 期间出现不稳定的崩溃（难以通过交互方式捕获）。 阅读指南：references/guide_d_coredump_analysis_dev.md

指南 E：核心转储分析（构建）

场景：构建期间出现不稳定的崩溃。 阅读指南：references/guide_e_coredump_analysis_build.md

指南 F：异步死锁识别

场景：出现不稳定的异步死锁。主线程卡在 uv_run 中。

阅读指南：references/guide_f_async_deadlock.md

保存调试产物

对 Agent 的重要指示： 成功获取堆栈回溯或跟踪日志后，必须将其保存到用户项目目录中的本地文件，以便在会话结束后保留。

1. 创建目录：确保项目根目录中存在名为 debug_artifacts 的目录。
2. 保存堆栈回溯：将 thread backtrace all 的完整输出写入 debug_artifacts/backtrace_<timestamp>.txt。
3. 保存跟踪日志：（仅在使用 Tracing Skill 时）

恢复环境

调试完成后，将 package.json 恢复为使用生产环境包：

node "<skill-root>/scripts/setup_debug_deps.cjs" --restore
pnpm install

使用与准备工作中相同的 <skill-root> 解析结果。