rspack-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rspack Debugging

Rspack调试

Overview

概述

This Skill guides you on how to capture the underlying crash state of Rspack (which is based on Rust). By using the LLDB debugger and Rspack packages with debug symbols, we can obtain detailed stack backtraces, which are crucial for pinpointing issues. The guides focus on non-interactive, automated debugging to easily capture backtraces.

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

Preparation

准备工作

Before starting, please ensure your environment meets the requirements.

Install LLDB: You must install the LLDB debugger.
- macOS: Run
```
xcode-select --install
```
- Linux: Install the
```
lldb
```
  package (e.g.,
```
apt-get install lldb
```
  )
- Detailed guide: references/lldb.md
Replace Debug Packages: Production packages like
```
@rspack/core
```
have debug symbols stripped. They must be replaced with the
```
@rspack-debug/*
```
series packages to see useful stack information.
Automatic Replacement Script:
bash
```
node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs
```
Running the above script will automatically add
```
pnpm.overrides
```
configuration to
```
package.json
```
, pointing Rspack packages to their corresponding Debug versions. Afterwards, please be sure to run
```
pnpm install
```
to update dependencies.

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

安装LLDB：您必须安装LLDB调试器。
- macOS：运行
```
xcode-select --install
```
- Linux：安装
```
lldb
```
  包（例如：
```
apt-get install lldb
```
  ）
- 详细指南：references/lldb.md
替换为调试包: 像
```
@rspack/core
```
这样的生产包已剥离调试符号。必须将其替换为
```
@rspack-debug/*
```
系列包才能查看有用的堆栈信息。
自动替换脚本:
bash
```
node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs
```
运行上述脚本会自动在
```
package.json
```
中添加
```
pnpm.overrides
```
配置，将Rspack包指向对应的调试版本。之后，请务必运行
```
pnpm install
```
来更新依赖。

Debugging Workflows

调试流程

Identify your specific scenario and follow the corresponding linked guide.

确定您的具体场景，然后遵循对应的链接指南。

Detailed Guides

详细指南

Detailed Guides

指南A：HMR期间崩溃

Guide A: Crash during HMR

—

Scenario: Stable Crash/Deadlock during DevServer HMR. Read Guide: references/guide_a_hmr_crash.md

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

Guide B: Crash during Build

指南B：构建期间崩溃

Scenario: Stable Crash/Deadlock during Build (or Unstable Build Crash that is frequent enough). Read Guide: references/guide_b_build_crash.md

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

Guide C: Attach to Stuck Process

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

Scenario: Unstable Deadlock during Build (happens randomly). Read Guide: references/guide_c_attach_to_stuck_process.md

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

Guide D: Coredump Analysis (Dev)

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

Scenario: Unstable Crash during DevServer HMR (hard to catch interactively). Read Guide: references/guide_d_coredump_analysis_dev.md

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

Guide E: Coredump Analysis (Build)

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

Scenario: Unstable Crash during Build. Read Guide: references/guide_e_coredump_analysis_build.md

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

Guide F: Async Deadlock Identification

指南F：异步死锁识别

Scenario: Unstable Async Deadlock. Main thread stuck in

uv_run

. Read Guide: references/guide_f_async_deadlock.md

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

uv_run

中。阅读指南: references/guide_f_async_deadlock.md

Saving Debug Artifacts

保存调试工件

Critical Instruction for Agents: When you successfully obtain a backtrace or a tracing log, you MUST save it to a local file in the user's project directory so it is preserved after the session.

Create Directory: Ensure a directory named
```
debug_artifacts
```
exists in the project root.

Save Backtraces: Write the full output of

thread backtrace all

debug_artifacts/backtrace_<timestamp>.txt

Save Tracing Logs: (Only if using Tracing Skill)

Agent关键说明: 当您成功获取回溯信息或跟踪日志后，必须将其保存到用户项目目录的本地文件中，以便会话结束后仍能保留。

创建目录：确保项目根目录下存在名为
```
debug_artifacts
```
的目录。

保存回溯信息：将

thread backtrace all

的完整输出写入

debug_artifacts/backtrace_<timestamp>.txt

。

保存跟踪日志：（仅在使用Tracing Skill时）

Environment Restoration

环境恢复

After debugging is complete, restore your

package.json

to use production packages:

bash

node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs --restore
pnpm install

调试完成后，恢复

package.json

以使用生产包：

bash

node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs --restore
pnpm install