使用 wasm-pack 和 React 将 Rust 编译为 WASM

标准的 Rust 到 WASM 工作流程使用两个工具：wasm-pack 负责协调构建流程（将 Rust 编译为 WASM、运行 wasm-bindgen、生成 npm 软件包），而 wasm-bindgen 负责生成 JavaScript 绑定，使 Rust 函数能够作为普通 JavaScript 函数被调用，并正确处理类型。

#[wasm_bindgen] 属性会将 Rust 函数、结构体和方法标记为导出到 JavaScript。没有这个属性，函数虽然会被编译为 WASM，但无法从 JavaScript 访问。为函数添加 #[wasm_bindgen] 注解后，wasm-bindgen 会生成 JavaScript 胶水代码，处理参数和返回值的转换。

一个最小的 Rust 导出函数如下：use wasm_bindgen::prelude::*; #[wasm_bindgen] pub fn add(a: u32, b: u32) -> u32 { a + b }。该函数接收两个无符号 32 位整数，并返回一个整数。wasm-bindgen 会生成 JavaScript 代码，用数字参数调用此函数，并返回数字结果。

请在 Rust 包目录中运行 wasm-pack build --target web。该命令会将 Rust 代码编译为 WASM，运行 wasm-bindgen 生成 JavaScript 绑定，并输出一个 pkg/ 目录，其中包含 .wasm 二进制文件、JavaScript 胶水模块和 TypeScript 类型定义。

请在 React 组件中导入生成的模块：import init, { add } from '../pkg/my_lib'。init 函数负责加载并实例化 WASM 二进制文件（请在 useEffect 中调用一次）。初始化后，直接调用导出的函数：const result = add(2, 3)。

对于超出基本数值范围的复杂数据，wasm-bindgen 提供了 js_sys::Array（JavaScript 数组）、js_sys::Object（JavaScript 对象）和 wasm_bindgen::JsValue（任意 JavaScript 值）。这些类型允许 Rust 函数接收和返回 JavaScript 数组及对象，但与基本类型相比会产生更多的序列化开销。

核心性能原则是：让数据保留在 WASM 内存中，并在那里完成所有计算。只传入一次数据，完成计算后只返回最终结果。避免在每个步骤都反复跨越 WASM 边界传输数据的模式。每次跨越边界的开销虽然很小，但在密集循环中会不断累积。

serde-wasm-bindgen 软件包支持使用 Serde 将 Rust 结构体序列化为 JavaScript 对象，以及将 JavaScript 对象反序列化为 Rust 结构体。请使用 #[derive(Serialize, Deserialize)] 为结构体添加注解，并调用 serde_wasm_bindgen::to_value() 和 from_value()。这是传递复杂结构化数据的标准方式。

长时间运行的 WASM 计算会阻塞其所在的线程。请将 WASM 放入 Web Worker 中，以便让 React 主线程保持空闲。创建一个用于初始化 WASM 模块并处理消息的 Worker 文件。通过 postMessage 向 Worker 发送数据，通过 message 事件接收结果，然后使用结果更新 React 状态。

wasm-pack 会为所有导出的函数和类型自动生成 TypeScript 声明文件（.d.ts）。这样，您的 React TypeScript 项目在调用 Rust 函数时即可获得完整的类型安全保障。生成的类型会反映 Rust 函数签名——add(a: number, b: number): number——从而让 IDE 自动补全正常工作。

WASM 二进制文件在优化后通常为 100kb-2MB。请在 Cargo.toml 发布配置中设置 opt-level = "z"，以启用 wasm-pack 构建中的 wasm-opt，从而积极优化文件大小。请使用 Content-Type: application/wasm 提供 WASM 文件，并启用 HTTP/2，以便浏览器高效地流式传输二进制文件。

Rust 代码中 #[wasm_bindgen] 属性的作用是什么？

wasm-pack build --target web 会将 Rust 编译为 WASM，并通过 wasm-bindgen 生成 JavaScript 绑定。请为导出的函数添加 #[wasm_bindgen] 注解。在 React 中导入 init 和导出的函数，在 useEffect 中调用 init()，然后像调用普通 JavaScript 函数一样调用这些函数。复杂结构体的序列化请使用 serde-wasm-bindgen。对于长时间运行的计算，请在 Web Worker 中运行 WASM，以便让 React 主线程保持空闲。