在 Web 中调试 Rust-Generated WebAssembly

1. 确保构建中包含 Debug 符号

为什么要启用 Debug 符号？

如果 .wasm 文件里没有包含 Debug 符号（即没有 "name" custom section），那么在浏览器开发者工具里看到的函数名称只会是诸如 wasm-function[42] 这样的编号，根本无法知道它对应 Rust 源码里的哪一个函数。

如何启用 Debug 符号？

1. Debug 构建（默认开启）

   • wasm-pack build --debug
   • cargo build (默认就是 debug 模式)

2. Release 构建（需手动开启）

   在 Cargo.toml 里添加：

   [profile.release]
   debug = true

此时即使在 release 模式下，也会保留函数名等调试信息。

⚠️ 启用 Debug 符号后，.wasm 文件体积会有所增加，建议仅在开发或内测时使用。

2. 使用浏览器 Console 进行日志输出

为什么要在浏览器 Console 中打印日志？

当你面对一个 WebAssembly + JavaScript 融合的应用时，最快的"初级调试"手段还是 log。可以借此了解数据流动、关键断点等信息，不用复杂地搭配 Debugger 或断点调试。

如何在 Rust 里调用浏览器的 console.log？

借助 web-sys crate：

extern crate web_sys;
use web_sys::console;

console::log_1(&"Hello, world!".into());

• console::log_1 代表只输出一个参数
• console::log_2, console::log_3 可以输出多个

使用 console.error

当你想要在控制台以错误形式突出显示（并保留可能的堆栈信息）时，改用：

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

这是 console.error 的相应接口，浏览器通常会自动加上堆栈信息以协助排查错误。

3. Panic 日志：console_error_panic_hook

Rust panic 默认会抛出一个 RuntimeError: unreachable executed 在浏览器里，很难溯源具体信息。

使用 console_error_panic_hook 即可将 panic 输出到控制台的错误日志中，还原 Rust panic 信息，便于快速定位问题：

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

只需要在初始化时调用 init_panic_hook()，后续所有的 panic 都会在浏览器控制台打印堆栈和报错信息，更接近原生 Rust 环境中的调试体验。

4. 使用调试器：现状与期待

当前 WebAssembly 的断点/单步调试

因为缺乏通用的元信息标准（与本地编程语言的 DWARF/CodeView 类似），大多数浏览器开发者工具只能显示原生 Wasm 指令层。你可以通过浏览器如 Chrome、Firefox、Edge 的 Debugger 面板查看：

• JS 代码断点、表达式查看
• .wasm 的汇编级指令

暂时无法直接在 Rust 源码级别设置断点或查看变量，这也是 W3C WebAssembly Debugging 组 正在努力推进的方向。

调试器在 JS 层的意义

尽管如此，JS 调试器仍能帮你查看 .wasm 模块调用栈与 JS 端的参数传递。当你的问题涉及 JS/Wasm 交互层面，这依旧是非常实用的。

5. 减少调试难度：在本地测试

分离 Wasm 与 JS 的交互逻辑

如果问题主要与 Rust 逻辑本身 （如算法、数据结构）相关，最好用 普通的 Rust 测试 来先定位：

#[test]
fn test_my_algorithm() {
    // ...
}

在本地可以享受成熟的调试工具、断点、IDE 等等，然后再移植到 .wasm 环境。

依赖 OS 的成熟工具

由于 .wasm 不具备完整的本地调试支持，如果可以先在本地调试通过，再编译到 WebAssembly，能节省大量麻烦。

注意，为了让普通的 Rust 测试通过编译和链接，你需要在 Cargo.toml 的 [lib] 中设置 crate-type 既包含 "cdylib" 又包含 "rlib"：

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

这样既可编译为 .wasm 使用，也可生成普通 Rust 库，方便本地测试。

6. 一图总结

7. 结语

• 现阶段：WebAssembly 调试链仍不如本地开发完善，但通过启用 debug 符号、console 日志、panic hook、以及本地先行测试，足以排查大多数典型问题。
• 未来：随着 WebAssembly Debugging 标准的推进，浏览器将逐渐支持更深入的源码级调试工具，让我们期待一个**"真·源码断点"**的时代尽快到来！