Emscripten 工具使用指南
本目录包含用于安装和使用 Emscripten 的工具脚本，用于将 Rust 编译的 WebAssembly 转换为 asm.js。
文件说明
install.bat- Emscripten 3.1.41 安装脚本gen-asm.bat- WASM 转 asm.js 转换脚本setup-env.bat- 环境变量设置脚本（安装后自动生成）.gitignore- Git 忽略文件配置
使用步骤
1. 安装 Emscripten
# 运行安装脚本
tools\emscripten\install.bat
前置要求:
- Git (用于下载 emsdk)
- Python 3.x (Emscripten 运行需要)
安装过程会:
- 下载 Emscripten SDK
- 安装指定版本 (3.1.41)
- 验证安装
- 创建环境设置脚本
2. 设置环境变量
每次使用前需要设置环境变量：
# 方法1: 使用自动生成的脚本
tools\emscripten\setup-env.bat
# 方法2: 手动运行
tools\emscripten\emsdk\emsdk_env.bat
3. 转换 WASM 为 asm.js
# 语法
tools\emscripten\gen-asm.bat <wasm文件路径> <输出路径>
# 示例1: 转换 pinball-physics
tools\emscripten\gen-asm.bat pinball-physics\target\wasm32-unknown-unknown\release\pinball_physics.wasm client-cocos\assets\wasm\pinball-asm.js
# 示例2: 转换 server-rust
tools\emscripten\gen-asm.bat server-rust\target\wasm32-unknown-unknown\release\server_rust.wasm client-cocos\assets\wasm\server-asm.js
工作流程示例
# 1. 首次安装
tools\emscripten\install.bat
# 2. 编译 Rust 项目为 WASM
cd pinball-physics
cargo build --target wasm32-unknown-unknown --release
cd ..
# 3. 设置 Emscripten 环境
tools\emscripten\setup-env.bat
# 4. 转换为 asm.js
tools\emscripten\gen-asm.bat pinball-physics\target\wasm32-unknown-unknown\release\pinball_physics.wasm client-cocos\assets\wasm\pinball-asm.js
输出文件使用
生成的 asm.js 文件可以在浏览器中使用：
<!DOCTYPE html>
<html>
<head>
<script src="pinball-asm.js"></script>
</head>
<body>
<script>
PinballModule().then(function(Module) {
// 使用 Module.ccall 调用 Rust 导出的函数
var result = Module.ccall('exported_function', 'number', ['number'], [42]);
console.log('Result:', result);
});
</script>
</body>
</html>
注意事项
- 版本固定: 当前使用 Emscripten 3.1.41 版本，确保兼容性
- 环境变量: 每次新开命令行窗口都需要重新设置环境变量
- 文件大小: asm.js 文件通常比 WebAssembly 大 3-5 倍
- 性能差异: asm.js 性能不如原生 WebAssembly
- 浏览器兼容: asm.js 主要用于兼容不支持 WebAssembly 的老旧浏览器
故障排除
安装问题
- 确保网络连接正常，能够访问 GitHub
- 检查 Git 和 Python 是否正确安装
- 如果下载失败，可以删除
emsdk目录重新运行
转换问题
- 确保 WASM 文件存在且格式正确
- 检查 Emscripten 环境变量是否设置
- 验证输出目录权限
运行时问题
- 确保在支持 asm.js 的浏览器中测试
- 检查 JavaScript 控制台的错误信息
- 验证导出函数名称是否正确