如何在onRuntimeInitialized外使用embind绑定的WASM类与函数？

问题根源 #

Emscripten编译生成的Wasm模块是异步初始化的：需要先加载Wasm二进制文件、完成编译与实例化，才能把embind绑定的C++类、函数挂载到module对象上。onRuntimeInitialized回调就是模块初始化完成的信号，在此之前访问module.Box这类绑定对象会得到undefined。

解决方案 #

1. 用Promise封装模块初始化（推荐，适用于Node.js/浏览器） #

把模块的初始化过程包装成Promise，让其他代码可以通过await等待模块就绪后再使用绑定对象，同时保证模块只初始化一次。

创建一个包装文件（比如molcpp-wrapper.js）：

// molcpp-wrapper.js
const modulePromise = new Promise(resolve => {
  const molcppModule = require('./molcpp');
  molcppModule.onRuntimeInitialized = () => {
    // 初始化完成，把模块对象传递出去
    resolve(molcppModule);
  };
});

module.exports = modulePromise;

在其他文件中使用：

// 其他业务文件
async function useMolcpp() {
  const molcpp = await require('./molcpp-wrapper');
  // 现在可以直接使用绑定的类和函数
  const box = new molcpp.Box();
  box.set_lengths_and_angles(new molcpp.Vec3(1, 2, 3), new molcpp.Vec3(90, 90, 90));
  console.log(box.matrix);
}

useMolcpp();

2. 将绑定对象挂载到全局（浏览器环境适用） #

如果是浏览器环境，可以在初始化完成后把需要的类/函数挂载到window全局对象，后续代码直接访问全局变量即可：

const module = require('./molcpp');

module.onRuntimeInitialized = () => {
  // 把绑定的类挂载到全局
  window.Box = module.Box;
  window.Vec3 = module.Vec3;
  
  // 也可以在这里执行初始化后的逻辑
  const box = new Box();
  box.set_lengths_and_angles(new Vec3(1,2,3), new Vec3(90,90,90));
};

后续其他脚本中，只要确保代码执行在模块初始化之后，就可以直接用new Box()。

3. 同步初始化（仅小模块推荐） #

如果你的模块体积很小，可以通过编译参数强制同步初始化，避免异步回调：
编译C++时添加以下Emscripten参数：

emcc your-code.cpp -o molcpp.js -s MODULARIZE=1 -s EXPORT_NAME="createMolcppModule" -s NO_EXIT_RUNTIME=1 -s ASYNCIFY=0

之后在JS中可以同步加载：

const createMolcppModule = require('./molcpp');
const module = createMolcppModule();
// 直接使用绑定对象
const box = new module.Box();

⚠️ 注意：大模块同步初始化会阻塞主线程，导致页面卡顿，不推荐在生产环境使用。

关键说明 #

不管用哪种方案，Emscripten模块只需要初始化一次，初始化完成后绑定的类和函数可以重复使用，不需要每次调用都重新初始化。

内容的提问来源于stack exchange，提问作者Roy Kid