Back to Details

debug-info-remapping

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug Info Remapping

调试信息映射

Description

说明

In Lynx, main thread script is encoded to bytecode and uses an external debugging information scheme. Under this scheme, the row and column numbers in the runtime error messages are not the actual row and column numbers. The row and column numbers need to be deciphered from the external 
debug-info.json
file.
debug-info.json format is as follows:
json
{
  "lepusNG_debug_info": {
    "function_info": [
      {
        "function_id": 1,
        "function_name": "App",
        "line_col": [
          { "line": 1, "column": 1 },
          { "line": 2, "column": 1 },
          { "line": 3, "column": 1 }
        ]
      }
    ]
  }
}
在Lynx中，主线程脚本会被编码为字节码，并采用外部调试信息方案。在该方案下，运行时错误消息中的行号和列号并非实际的源代码行号和列号，需要从外部的
debug-info.json
文件中解析出真实位置。
debug-info.json的格式如下：
json
{
  "lepusNG_debug_info": {
    "function_info": [
      {
        "function_id": 1,
        "function_name": "App",
        "line_col": [
          { "line": 1, "column": 1 },
          { "line": 2, "column": 1 },
          { "line": 3, "column": 1 }
        ]
      }
    ]
  }
}

When to Apply

适用场景

This skill is useful when you want to remap the 
function_id:pc_index
to the original source code position.
When the user encounters a runtime error message with function_id:pc_index, along with 
main-thread.js
and 
debug-info.json
in the error message, for example:
main-thread.js exception: App render failed at main thread backtrace:
    at App (file:///main-thread.js:1356:13)
    at doRender (file:///main-thread.js:1002:12)
    at call (native)
    at render (file:///main-thread.js:466:52)
    at _renderToString (file:///main-thread.js:1001:569)
    at renderToString (file:///main-thread.js:998:191)
    at renderMainThread (file:///main-thread.js:766:45)
    at renderPage (file:///main-thread.js:853:69)
Where 
function_id:pc_index
is 
1356:13
.
当你需要将
function_id:pc_index
映射回原始源代码位置时，该技能会非常有用。
当用户遇到包含
function_id:pc_index
的运行时错误消息，且错误消息中附带
main-thread.js
和
debug-info.json
时，例如：
main-thread.js exception: App render failed at main thread backtrace:
    at App (file:///main-thread.js:1356:13)
    at doRender (file:///main-thread.js:1002:12)
    at call (native)
    at render (file:///main-thread.js:466:52)
    at _renderToString (file:///main-thread.js:1001:569)
    at renderToString (file:///main-thread.js:998:191)
    at renderMainThread (file:///main-thread.js:766:45)
    at renderPage (file:///main-thread.js:853:69)
其中
function_id:pc_index
为
1356:13
。

Workflow

操作流程

1. Ask the User for the 
function_id:pc_index

1. 向用户索要
function_id:pc_index

User should provide the 
function_id:pc_index
in the error message. Or give you the full backtrace.
You should check if it is a main-thread backtrace. Since background thread backtrace does not need remapping.
用户需要提供错误消息中的
function_id:pc_index
，或者完整的调用栈信息。
你需要检查该调用栈是否属于主线程，因为后台线程的调用栈不需要进行映射。

2. Find the Corresponding Position in debug-info.json

2. 在debug-info.json中查找对应位置

Ask the user for the 
debug-info.json
path. For example in a rspeedy project with 
main
entry it will locate at:
  • main-thread.js
    : 
    $PROJECT_DIR/dist/.rspeedy/main/main-thread.js
  • debug-info.json
    : 
    $PROJECT_DIR/dist/.rspeedy/main/debug-info.json
If the user uses 
rspeedy build
and there is no 
.rspeedy
folder, remind them to build the project with 
DEBUG='rspeedy,rsbuild' rspeedy build
.
向用户索要
debug-info.json
的路径。例如，在以
main
为入口的rspeedy项目中，文件位置如下：
  • main-thread.js
    : 
    $PROJECT_DIR/dist/.rspeedy/main/main-thread.js
  • debug-info.json
    : 
    $PROJECT_DIR/dist/.rspeedy/main/debug-info.json
如果用户使用
rspeedy build
构建后没有生成
.rspeedy
文件夹，提醒他们使用
DEBUG='rspeedy,rsbuild' rspeedy build
命令重新构建项目。

3. Run the remapping script

3. 运行映射脚本

For each 
function_id:pc_index
pair in the stack trace, run the remapping script.
bash
node ${CLAUDE_PLUGIN_ROOT}/skills/debug-info-remapping/scripts/index.mjs $PROJECT_DIR/[dist]/.rspeedy/[main]/debug-info.json $function_id $pc_index
针对调用栈中的每一对
function_id:pc_index
，运行映射脚本。
bash
node ${CLAUDE_PLUGIN_ROOT}/skills/debug-info-remapping/scripts/index.mjs $PROJECT_DIR/[dist]/.rspeedy/[main]/debug-info.json $function_id $pc_index

4. Output the Remapped Position

4. 输出映射后的位置

The remapping script will output the remapped position in the format of 
line:column
.
You should output the remapped position for each 
function_id:pc_index
pair.
Replace the 
function_id:pc_index
pair in the stack trace with the remapped position and show the remapped stack trace.
映射脚本会以
line:column
的格式输出映射后的位置。
你需要为每一对
function_id:pc_index
输出对应的映射位置。
将调用栈中的
function_id:pc_index
替换为映射后的位置，并展示更新后的调用栈。

5. Show the Remapped Stack Trace

5. 展示映射后的调用栈

If you can reach the 
main-thread.js
file, show the remapped stack trace with the remapped positions source code.
The final output should be something like this:
log
main-thread.js exception: App render failed at main thread backtrace:
    at App (./dist/.rspeedy/main/main-thread.js:9368:56)
    at doRender (./dist/.rspeedy/main/main-thread.js:7237:44)
    at call (native)
    at render (./dist/.rspeedy/main/main-thread.js:3706:72)
    at _renderToString (./dist/.rspeedy/main/main-thread.js:7177:78)
    at renderToString (./dist/.rspeedy/main/main-thread.js:7067:91)
    at renderMainThread (./dist/.rspeedy/main/main-thread.js:5423:113)
    at renderPage (./dist/.rspeedy/main/main-thread.js:6199:46)

   ╭─[5:55]
 3 │ export function App() {
 4 │   if (__MAIN_THREAD__) {
 5 │     throw new Error('App render failed at main thread');
   ·                                                      ─┬
   ·                                                       ╰── main-thread.js exception: App render failed at main thread backtrace
 6 │   }
 7 │
   ╰────

   ... (the same for other callstacks such as doRender, call, render, _renderToString, renderToString, renderMainThread, renderPage here)

Files used:

  - Debug Info: ./dist/.rspeedy/main/debug-info.json
  - Source File: ./dist/.rspeedy/main/main-thread.js
The 
./dist/.rspeedy/main/main-thread.js:9368:56
will make sure it is clickable in the editor/terminal.
如果可以访问
main-thread.js
文件，展示包含映射位置对应源代码的调用栈。
最终输出示例如下：
log
main-thread.js exception: App render failed at main thread backtrace:
    at App (./dist/.rspeedy/main/main-thread.js:9368:56)
    at doRender (./dist/.rspeedy/main/main-thread.js:7237:44)
    at call (native)
    at render (./dist/.rspeedy/main/main-thread.js:3706:72)
    at _renderToString (./dist/.rspeedy/main/main-thread.js:7177:78)
    at renderToString (./dist/.rspeedy/main/main-thread.js:7067:91)
    at renderMainThread (./dist/.rspeedy/main/main-thread.js:5423:113)
    at renderPage (./dist/.rspeedy/main/main-thread.js:6199:46)

   ╭─[5:55]
 3 │ export function App() {
 4 │   if (__MAIN_THREAD__) {
 5 │     throw new Error('App render failed at main thread');
   ·                                                      ─┬
   ·                                                       ╰── main-thread.js exception: App render failed at main thread backtrace
 6 │   }
 7 │
   ╰────

   ... (此处可添加其他调用栈如doRender、call、render、_renderToString、renderToString、renderMainThread、renderPage的对应内容)

Files used:

  - Debug Info: ./dist/.rspeedy/main/debug-info.json
  - Source File: ./dist/.rspeedy/main/main-thread.js
./dist/.rspeedy/main/main-thread.js:9368:56
格式的路径可以在编辑器/终端中点击跳转。