当前位置：首页 > news >正文

调试 Rust 生成的 WebAssembly

news 2025/8/2 9:07:04

一、开启调试符号

默认情况下，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 信息输出到控制台。

添加依赖：

[dependencies]
console_error_panic_hook = "0.1"

在初始化入口设置 Panic Hook：

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

在 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 侧的调试需求。

单元测试（#[test]）
- 在纯 Rust 环境下编写测试，复用 cargo test 的成熟调试工具。
- 如果你的库需要在 WASM 和 Native 双环境下运行，可在 Cargo.toml 中允许 rlib：
```
[lib]
crate-type = ["cdylib", "rlib"]
```
集成测试（wasm-bindgen-test）
- 对 JS 交互或 Web API 依赖场景，使用 wasm-bindgen-test 在 headless 浏览器里写测试。
- 在 CI 中跑测试，比手动调试更可靠。
QuickCheck 风格测试
- 引入 quickcheck 等 property-based 测试，自动生成输入并缩小失败用例，帮助快速定位逻辑错误。