在 React 中加载 WASM 模块

浏览器标准的 WASM 模块加载方式是 WebAssembly.instantiateStreaming(fetch(url), importObject)。这种方式会在下载 WASM 二进制文件的同时以流式方式传输，立即开始编译，并解析为一个包含模块和实例的对象。这是生产环境中最高效的加载方式。

Vite 和 webpack 支持使用动态导入语法将 WASM 文件作为 ES 模块导入：import('./module.wasm')。加载机制由构建工具处理。这种方式可以自然地集成代码拆分：只有在执行导入代码时才会加载 WASM 模块。

加载 WASM 模块是一项异步操作，应放在 useEffect 钩子中。请在副作用中获取并实例化模块，将导出的函数存储在状态或引用中，并在初始化完成后更新组件。空依赖数组可以确保每次组件挂载时模块只加载一次。

请将 WASM 实例存储在 useRef 中，以避免初始化时重新渲染；如果该实例是整个应用共享的单例，也可以将其存储在模块级变量中。将实例存储在 useState 中同样可行，但实例可用时会额外触发一次重新渲染，对于简单场景来说可以接受。

对于必须依赖 WASM 模块才能运行的组件，请将组件包裹在 React.lazy 中，并在 Suspense 边界内渲染。WASM 模块可以作为动态导入的一部分加载。模块初始化期间，Suspense 会显示备用骨架屏，从而提供流畅的加载体验。

在典型网络条件下，WASM 模块通常需要 100-500 毫秒来加载和实例化，具体取决于模块大小和设备速度。初始化进行期间，请始终显示加载指示器（骨架屏、加载转圈或进度条）。如果在没有任何视觉反馈的情况下阻塞 UI 等待 WASM 初始化，用户会感觉应用卡住了。

实例化后，可以通过 instance.exports.myFunction() 访问 WASM 函数。使用 wasm-bindgen（Rust 工具链）时，生成的 JavaScript 胶水模块会直接导出这些函数，并进行适当的类型强制转换。您可以像调用普通 JavaScript 函数一样调用它们，使用 Rust 源代码中定义的类型。

请像调用任何同步函数一样，从 React 事件处理函数中调用 WASM 函数：function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }。WASM 函数调用是同步的：在计算完成前，它会阻塞调用线程。这也是长时间运行的操作应放入工作线程中的另一个原因。

WASM 初始化可能会失败：获取操作可能失败，模块可能不兼容，或者浏览器可能缺少某项功能。请将依赖 WASM 的组件包裹在 React 错误边界中，以捕获初始化失败并显示备用内容。请记录错误以便调试，并在可能的情况下提供平稳降级方案。

Vite 需要两个插件才能正确处理 WASM 模块：vite-plugin-wasm 负责处理 WASM 文件导入，vite-plugin-top-level-await 则启用某些 WASM 胶水代码使用的顶层 await。请安装这两个插件，并将它们添加到 plugins 数组中的 vite.config.ts 内。

对于 webpack 项目，请在 webpack.config.js 中启用 asyncWebAssembly 实验功能：experiments: { asyncWebAssembly: true }。这样浏览器就可以异步加载通过 import() 导入的 WASM 文件。Create React App 项目需要执行配置弹出，或使用 CRACO 添加此配置。

请使用 WebAssembly.instantiateStreaming(fetch(url)) 或在 useEffect 中动态导入 WASM。将实例存储在 useRef 或模块单例中。在 100-500 毫秒的初始化期间显示加载状态。通过 instance.exports.fn() 访问导出内容。使用错误边界处理初始化失败。使用 vite-plugin-wasm 和 vite-plugin-top-level-await 配置 Vite。