Node.js调试Wasm断点不命中，根本原因是Node.js默认不加载DWARF调试段，必须同时满足：Node.js≥18.17.0、启用--experimental-wasm-dwarf、设置NODE_OPTIONS="--enable-source-maps"，且WASI模块因缺乏原生支持无法用type:"node"调试。
Node.js 环境下断点不命中，先看 --experimental-wasm-dwarf 有没有启用
VSCode 调试器本身不解析 .wasm 中的 DWARF 调试信息，Node.js 默认也忽略它。哪怕你用 cargo build --target wasm32-unknown-unknown -Z unstable-options --codegen debuginfo=2 编出了带完整调试段的 .wasm，Node.js 仍会跳过——除非显式加启动参数。
必须满足三个条件：
-
node -v≥ 18.17.0（旧版如 16.x 加 flag 也无效） - 运行时带上
--experimental-wasm-dwarf - 环境变量设
NODE_OPTIONS="--enable-source-maps"（否则 JS glue code 的 source map 不生效）
在 .vscode/launch.json 中，不能只写 command 字段；必须把 flag 塞进 runtimeArgs：
{
"type": "node",
"request": "launch",
"name": "Debug Wasm (Node)",
"program": "${workspaceFolder}/index.js",
"runtimeArgs": ["--experimental-wasm-dwarf"],
"env": { "NODE_OPTIONS": "--enable-source-maps" }
}
浏览器环境调试失败，重点查 wasm-pack build --debug 和 .wasm.map 文件是否存在
VSCode 无法直接加载 .wasm 文件调试，它依赖浏览器 DevTools + source map 链路。如果断点灰掉、调用栈里看不到 Rust/C 源码行，大概率是 map 文件没生成或路径不对。
验证步骤：
- Rust 用户：确保用
wasm-pack build --debug（不是build -d），且Cargo.toml中未设置debug = false - 构建后检查
pkg/*.wasm.map是否存在，且内容为合法 JSON（非空、有sources和mappings字段） -
launch.json中webRoot必须指向 HTML 所在目录，否则 VSCode 找不到 map 文件对应源码位置 - 别用
file://协议打开页面——Chrome 会禁用 wasm 加载；改用live-server或python3 -m http.server
WASI 模块在 Node 里调试不了？因为 type: "node" 不支持原生 WASI
如果你的 .wasm 是用 wasm32-wasi 目标编译的（比如 Rust 里 rustup target add wasm32-wasi），那它依赖 WASI 系统调用（如 __wasi_proc_exit）。Node.js 的 type: "node" 调试模式根本不提供 WASI 实现，所以 WebAssembly.instantiate() 会直接抛 LinkError。
两种解法：
- 换目标：Rust 改用
wasm32-unknown-unknown，C/C++ 加-s STANDALONE_WASM=1，走纯裸模块路线 - 换运行时：用
iwasm（WAMR）或wasmer等支持 WASI 的 runtime，并配对应调试器（VSCode 目前无官方插件，需手动 attach）
注意：launch.json 里 type 写成 "node" 对 WASI 模块毫无意义，它只会卡在 instantiate 阶段。
tasks.json 编译任务跑不通？90% 是终端里 wasm-pack 或 emcc 找不到
VSCode 不编译 wasm，它只是调外部命令。如果 Ctrl+Shift+B 报 command not found，问题不在配置格式，而在 PATH。
排查顺序：
- 打开 VSCode 内置终端（Ctrl+`），直接输
wasm-pack --version或emcc --version—— 必须有输出 - macOS 用户特别小心：从 Dock 启动 VSCode 时，它不继承 shell 的 PATH（比如
$HOME/.cargo/env）；改用已执行过source $HOME/.cargo/env的终端中运行code . - Windows 用户若用 emsdk，必须先运行
emsdk_env.bat，再启动 VSCode -
tasks.json中command字段别写死路径（如./emsdk/upstream/emscripten/emcc），优先用"command": "emcc"，靠 PATH 解析
真正容易被忽略的是：WASI 模块和浏览器模块对工具链要求完全不同，但错误现象高度相似——都是“加载失败”或“断点不亮”。这时候得先确认你到底想在哪跑，再选对目标、编译器和调试通道。
