# 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 ```batch # 运行安装脚本 tools\emscripten\install.bat ``` **前置要求:** - Git (用于下载 emsdk) - Python 3.x (Emscripten 运行需要) 安装过程会: - 下载 Emscripten SDK - 安装指定版本 (3.1.41) - 验证安装 - 创建环境设置脚本 ### 2. 设置环境变量每次使用前需要设置环境变量： ```batch # 方法1: 使用自动生成的脚本 tools\emscripten\setup-env.bat # 方法2: 手动运行 tools\emscripten\emsdk\emsdk_env.bat ``` ### 3. 转换 WASM 为 asm.js ```batch # 语法 tools\emscripten\gen-asm.bat <输出路径> # 示例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 ``` ## 工作流程示例 ```batch # 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 文件可以在浏览器中使用： ```html ``` ## 注意事项 1. **版本固定**: 当前使用 Emscripten 3.1.41 版本，确保兼容性 2. **环境变量**: 每次新开命令行窗口都需要重新设置环境变量 3. **文件大小**: asm.js 文件通常比 WebAssembly 大 3-5 倍 4. **性能差异**: asm.js 性能不如原生 WebAssembly 5. **浏览器兼容**: asm.js 主要用于兼容不支持 WebAssembly 的老旧浏览器 ## 故障排除 ### 安装问题 - 确保网络连接正常，能够访问 GitHub - 检查 Git 和 Python 是否正确安装 - 如果下载失败，可以删除 `emsdk` 目录重新运行 ### 转换问题 - 确保 WASM 文件存在且格式正确 - 检查 Emscripten 环境变量是否设置 - 验证输出目录权限 ### 运行时问题 - 确保在支持 asm.js 的浏览器中测试 - 检查 JavaScript 控制台的错误信息 - 验证导出函数名称是否正确 ## 相关链接 - [Emscripten 官方文档](https://emscripten.org/docs/) - [asm.js 规范](http://asmjs.org/) - [Rust WebAssembly 指南](https://rustwasm.github.io/docs/book/)