直接运行emcc --version可验证Emscripten是否安装就绪；若报command not found或提示缺少Python/Node.js，说明环境未配好，需通过emsdk activate latest并正确加载emsdk_env.sh（macOS/Linux）或emsdk_env.ps1（Windows）来解决。
确认 Emscripten 安装和环境是否就绪
直接运行 emcc --version，如果报错 command not found 或提示找不到 Python、Node.js，说明环境没配好。Emscripten 不是单个二进制，而是一套基于 Python 的构建系统，依赖 Node.js（用于运行生成的 JS 胶水代码）和 CMake（若用 CMake 构建）。官方推荐用 emsdk 管理版本，避免手动 PATH 混乱。
常见踩坑点：
-
emsdk install latest后必须emsdk activate latest，否则emcc不在 PATH 中 - Windows 上用 PowerShell 运行
emsdk.ps1前要先执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - macOS / Linux 下激活后建议新开终端，或手动 source
source ./emsdk_env.sh
用 emcc 编译单个 .cpp 文件为 WASM + JS 胶水
emcc 是核心编译器，行为接近 gcc，但默认输出是 JS + WASM 组合，不是纯 WASM。想导出函数供 JS 调用，得显式声明并控制导出方式。
例如有 add.cpp：
立即学习“C++免费学习笔记（深入）”；
extern "C" int add(int a, int b) {
return a + b;
}
编译命令：
emcc add.cpp -o add.js -s EXPORTED_FUNCTIONS='["_add"]' -s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap"]'
关键点：
-
EXPORTED_FUNCTIONS必须带下划线前缀（C 函数名 mangling），且用数组语法；漏掉引号或写成['add']会静默失败 -
EXPORTED_RUNTIME_METHODS才能让生成的 JS 提供ccall/cwrap接口，否则只能靠Module.onRuntimeInitialized手动调用 - 不加
-s STANDALONE_WASM=1就不会输出纯.wasm文件——它默认依赖 JS 胶水做内存管理、堆初始化等
用 CMake + Emscripten 构建多文件项目
CMake 是主流选择，但必须用 Emscripten 提供的 toolchain 文件，不能只改 CMAKE_CXX_COMPILER。否则链接阶段会缺 sysroot、无法识别 -s 参数。
典型流程：
- 确保
EMSCRIPTEN环境变量指向emsdk/upstream/emscripten目录 - 运行：
cmake -B build-wasm -S . -G "Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=$EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake
- 生成的
build-wasm/CMakeCache.txt里应看到CMAKE_SYSTEM_NAME:STRING=Emscripten，否则 toolchain 没生效 - 在
CMakeLists.txt中用target_compile_options(target PRIVATE -s EXPORTED_FUNCTIONS=...)传-s参数，不能写进add_compile_options—— 那是给 C++ 编译器的，不是给 linker 的
调试 WASM 导出函数调用失败的问题
最常见现象：JS 里 Module.ccall('add', ...) 报错 cannot call method 'add' on undefined，或控制台显示 no function table for function pointer。
排查顺序：
- 检查浏览器控制台是否有
uncaught RuntimeError: abort(...)，通常意味着 WASM 初始化失败（比如内存不足、JS 胶水没加载完） - 打开生成的
.js文件，搜索function add(或_add:，确认函数是否真被导出；若没出现，说明EXPORTED_FUNCTIONS写错或函数未定义为extern "C" - 用
wabt工具反编译：wabt/bin/wasm-decompile add.wasm | grep add，看 WASM 里是否存在对应导出符号 - 若用
dynamicLibraries加载多个 WASM，注意 Emscripten 默认不支持跨模块符号引用——每个模块是隔离的，需用MODULARIZE=1+ 手动importObject注入
WASM 本身不处理符号可见性，一切由 Emscripten 的胶水 JS 控制；导出逻辑发生在 JS 层，不是 WASM 二进制层。这点容易混淆。
