必须显式指定-s exported_functions='["_func"]'并确保函数带emscripten_keepalive和extern "c",否则链接期被裁剪;js需等待module.onruntimeinitialized或await init()后调用,且字符串/数组须手动管理线性内存。

导出的 C++ 函数在 JS 中找不到?检查 EXPORTED_FUNCTIONS 和 EXPORTED_RUNTIME_METHODS
WASM 模块默认不暴露任何 C++ 符号,即使你写了 extern "C" void my_func(); 并用 EMSCRIPTEN_KEEPALIVE 标记,JS 仍可能报 Module._my_func is not a function。根本原因是 Emscripten 的链接阶段会 strip 掉未声明导出的符号。
编译时必须显式告诉 Emscripten 哪些函数要导出:
- 用
-s EXPORTED_FUNCTIONS='["_my_func", "_another_func"]'(注意下划线前缀,C++ 函数名会被 mangling,但extern "C"+EMSCRIPTEN_KEEPALIVE后是 C 风格符号,带下划线) - 如果要用
ccall/cwrap,还需加-s EXPORTED_RUNTIME_METHODS='["ccall","cwrap"]' - 若启用了
-s STANDALONE_WASM=1,则无法用ccall,只能靠 WebAssembly JS API 手动调用,此时导出列表仍需EXPORTED_FUNCTIONS
ccall 调用失败:参数类型和内存布局不匹配
C++ 函数接收 int、float 等基础类型没问题,但一旦涉及指针(比如 char*、数组、结构体),JS 侧必须手动管理 WASM 内存,否则读写越界或返回乱码。
常见错误场景:
- 传字符串:JS 中不能直接传
"hello",得先用Module.lengthBytesUTF8和Module.stringToUTF8写入线性内存,再把偏移量传给 C 函数 - 读返回字符串:C 返回
char*时,JS 要用Module.UTF8ToString(ptr)解码,且确保该指针指向的是 malloc 分配或静态字符串(栈上局部变量地址在函数返回后失效) - 传入数组:用
Module._malloc(size)分配,Module.HEAP32.set(...)写入,调用完记得Module._free(ptr)
WASM 加载完成前就调用函数?等 Module.onRuntimeInitialized 或用 Promise
Emscripten 生成的 JS 胶水代码是异步初始化的:下载 .wasm、编译、实例化、运行全局构造函数、设置堆……这些都完成后,导出函数才真正可用。直接在 script 标签里写 Module._my_func() 会报 undefined。
正确做法有两种:
- 监听
Module.onRuntimeInitialized = () => { Module._my_func(); } - 如果用现代打包方式(如
MODULARIZE=1),可 import 模块并 await 初始化:import init, { my_func } from './module.js'; await init(); my_func(); // 这里才是安全的
注意:不要依赖 DOMContentLoaded 或 window.onload,它们和 WASM 初始化无关。
为什么 C++ 里 std::string 或 std::vector 不能直接导出?
WASM 没有跨语言的 ABI,std::string 是 C++ 运行时对象,其内存布局、分配器、析构逻辑 JS 完全无法理解。试图导出或传入这类类型,轻则崩溃,重则静默内存损坏。
可行方案只有三种:
- 彻底避免:导出函数只用 C 风格接口(
const char*,int*,float*,size_t) - 用
std::string仅作内部实现,输入输出仍走裸指针 + 长度参数,例如void process_text(const char* input, size_t len, char* output, size_t out_size) - 借助 Emscripten 的
EM_JS宏,在 C++ 里直接写 JS 逻辑(适合简单 glue 场景,但破坏了纯 WASM 的可移植性)
最易被忽略的是:C++ 全局 std::string 变量在模块卸载时不会自动析构——如果 WASM 实例被反复创建销毁,会导致内存泄漏。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











