C++转WASM教程：Emscripten入门指南

用emcc编译C++到WASM最简流程是执行emcc hello.cpp -o hello.js，生成hello.js（胶水代码）和hello.wasm（二进制模块）；浏览器需JS加载WASM，不能直接运行.wasm文件。

用 emcc 编译 C++ 到 WASM 最简流程

直接运行 emcc 就能生成 WASM，不需要额外配置构建系统。它本质是 Clang 的封装，所以几乎所有 C++ 语法和标准库（如 std::vector、std::string）都可用，但默认链接的是 Emscripten 自带的 musl libc 和 libc++。

最基础命令：

emcc hello.cpp -o hello.js

这会生成 hello.js（胶水代码）和 hello.wasm（二进制模块）。浏览器不能直接执行 .wasm 文件，必须靠 JS 加载并实例化，所以 emcc 默认输出 JS 胶水——除非你显式禁用。

• -o hello.wasm 不行：emcc 不接受纯 .wasm 输出目标，会报错 error: cannot emit a .wasm file without JavaScript support
• 想只生成 WASM？加 --no-entry --standalone-wasm，但此时代码不能调用任何 libc 函数（比如 printf、malloc），否则链接失败
• emrun hello.html 可直接起一个本地服务器打开页面，避免跨域加载 WASM 的报错

导出 C++ 函数供 JS 调用的关键写法

默认编译后，C++ 函数不会自动暴露给 JS。必须用 EMSCRIPTEN_KEEPALIVE 宏标记，或通过 -s EXPORTED_FUNCTIONS 显式声明。

例如，让 JS 能调用 add(int, int)：

#include 

EMSCRIPTEN_KEEPALIVE
int add(int a, int b) {
  return a + b;
}

然后编译时加 -s EXPORTED_FUNCTIONS='["_add"]'（注意下划线前缀，C++ 符号经编译器修饰后默认带下划线）；或者更简单：加 -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap"]'，这样 JS 里就能用 Module.ccall('add', 'number', ['number', 'number'], [1, 2])。

• 不加 EMSCRIPTEN_KEEPALIVE 或未在 EXPORTED_FUNCTIONS 中列出的函数，会被 LTO（Link-Time Optimization）直接丢弃
• C++ 类成员函数无法直接导出，需包装成自由函数
• 返回 std::string 会出问题：WASM 线性内存中没有自动管理字符串生命周期的机制，应改用 const char* + malloc + 手动释放，或用 UTF8ToString() 在 JS 侧转换

常见报错与绕过方法

编译失败往往不是语法问题，而是 Emscripten 的运行时约束导致的。

• undefined symbol: __cxa_throw：用了 throw 但没开异常支持。加 -s DISABLE_EXCEPTION_CATCHING=0（默认关闭，开启后体积增大、性能下降）
• undefined symbol: malloc：手动写了 malloc 调用，但链接时没启用动态内存分配。加 -s ALLOW_MEMORY_GROWTH=1 和 -s MALLOC=emmalloc（推荐）或 dlmalloc
• file not found: SDL2：Emscripten 自带 SDL2 支持，但需用 -lSDL2 链接，且头文件路径已内置，不用额外 -I
• JS 控制台报 abort(CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found 3c 21 44 4f：说明服务器返回了 HTML（比如 404 页面）而不是 .wasm 文件，检查网络面板确认 MIME 类型是否为 application/wasm

调试 WASM 的实际手段

不能像本地 C++ 那样用 gdb，但有几条有效路径：

• 加 -g 编译，然后在 Chrome DevTools 的 Sources → Wasm 标签页里看到带符号的 WASM 函数名（需启用 WebAssembly Debugging (preview) 实验性功能）
• 用 console.log 插桩：在 C++ 里调用 EM_ASM_({ console.log('here'); });，或传参：EM_ASM_INT({ console.log('value:', $0); }, x);
• emrun --browser firefox 启动 Firefox，其 WASM 调试器对局部变量支持更好
• 生成源码映射（-gsource-map-base http://localhost:8080/）后，Chrome 可将 WASM 指令映射回 C++ 行号——但仅限同步函数，异步回调（如事件循环）仍难追踪

真正卡住的时候，往往不是编译或导出问题，而是 JS 和 WASM 之间内存边界没理清：比如把 JS 字符串直接传进 C++ 函数当 char*，却不先用 lengthBytesUTF8 + stringToUTF8 写入线性内存。