调试 Rust 生成的 WebAssembly

一、开启调试符号

默认情况下，Rust 在 Release 模式下会剔除所有调试信息。缺少符号表时，Chrome/Firefox 报出的堆栈只会是 wasm-function[42]，而无法看到你写的函数名。

• Debug 构建

  wasm-pack build --debug
  # 或者
  cargo build
  

  Debug 模式会自动保留调试符号，自带 name 自定义段，可以在浏览器 DevTools 看到 Rust 函数签名。

• Release 模式下保留符号
  如果你需要在 Release 模式下也能调试，请在 Cargo.toml 中添加：

  [profile.release]
  debug = true
  

  这样编译出的 .wasm 会包含 DWARF 符号段，堆栈信息更友好。

二、在 JS 控制台打印日志

调试中，打印日志往往是最直接的手段。在浏览器里，我们可以通过 console.log、console.error 输出调试信息。

1. 使用 web-sys 调用控制台 API

在 Rust 里，依赖 web-sys 并直接调用：

use wasm_bindgen::prelude::*;
use web_sys::console;

#[wasm_bindgen]
pub fn greet(name: &str) {
    console::log_1(&format!("Hello, {}!", name).into());
}

• console::log_1：打印一个值。
• console::log_2 等：可以打印多达 4 个值。

2. 用 console.error 打印堆栈

console::error_1(&"Something went wrong!".into());

console.error 会在 DevTools 中自动附带调用堆栈，便于定位。

三、捕获并打印 Rust Panic

当 Rust 代码 panic!() 时，WASM 会抛出 RuntimeError: unreachable executed，根本看不出具体原因。可通过 console_error_panic_hook crate 将 Panic 信息输出到控制台。

1. 添加依赖：

   [dependencies]
   console_error_panic_hook = "0.1"
   

2. 在初始化入口设置 Panic Hook：

   use wasm_bindgen::prelude::*;
   
   #[wasm_bindgen]
   pub fn init_panic_hook() {
       console_error_panic_hook::set_once();
   }
   

3. 在 JS 层调用一次：

   import init, { init_panic_hook } from "./pkg/your_wasm.js";
   
   async function run() {
     await init();
     init_panic_hook();
     // 之后的 panic 会以 Rust 的格式化信息打印在 console.error
   }
   run();
   

四、在浏览器调试 WASM

当前各大浏览器对 WASM 源级调试支持有限，只能看到汇编级别指令。常见做法：

• Chrome DevTools / Firefox Debugger

  • 可以设置断点在 .wasm 的导出函数入口；
  • 只能单步原生 WebAssembly 指令，而非 Rust 源代码。

• 观察 JS 和 Web API 交互
  对于大部分问题，往往是 Rust 与 JS 之间的数据传递或 Web API 使用异常更常见。此时在 JS 侧打断点/单步，比在 WASM 侧更高效。

展望：W3C 正在推进 WASM 源级调试规范，未来有望直接定位到 Rust *.rs 行。

五、尽量在本地复现并减少 WASM 调试

最佳实践：将业务逻辑尽量在本地 Rust 测试中覆盖，减少在 WASM 侧的调试需求。

1. 单元测试（#[test]）

   • 在纯 Rust 环境下编写测试，复用 cargo test 的成熟调试工具。

   • 如果你的库需要在 WASM 和 Native 双环境下运行，可在 Cargo.toml 中允许 rlib：

     [lib]
     crate-type = ["cdylib", "rlib"]
     

2. 集成测试（wasm-bindgen-test）

   • 对 JS 交互或 Web API 依赖场景，使用 wasm-bindgen-test 在 headless 浏览器里写测试。
   • 在 CI 中跑测试，比手动调试更可靠。

3. QuickCheck 风格测试

   • 引入 quickcheck 等 property-based 测试，自动生成输入并缩小失败用例，帮助快速定位逻辑错误。

结语

调试 Rust → WASM 项目时，你可以结合以下方法：

1. 开启调试符号，让堆栈显示真实函数名。
2. 大量使用 console.log / console.error 追踪数据。
3. 安装 Panic Hook，把 Rust 的 panic 信息打印到控制台。
4. 利用浏览器 DevTools 观察 JS/WASM 边界。
5. 优先在本地 Rust 测试覆盖，减少在生产环境下的 WASM 调试需求。

随着 WebAssembly 调试生态的不断完善，相信未来能实现真正的源级调试，带来更流畅的开发体验。希望本文能帮你在现有条件下，大幅提升 Rust/WASM 项目的可调试性！