Rust 编译到 WebAssembly 完全指南

# 安装 Rust（已安装可跳过）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 添加 WASM32 编译目标
rustup target add wasm32-unknown-unknown

# 安装 wasm-pack（核心打包工具）
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# 验证安装
wasm-pack --version

# 安装 cargo-generate
cargo install cargo-generate

# 使用官方模板创建项目
cargo generate --git https://github.com/rustwasm/wasm-pack-template
# → 输入项目名：wasm-hello

// src/lib.rs
use wasm_bindgen::prelude::*;

// 这个宏会自动：
// 1. 将 greet 函数注册为 WASM 模块的导出
// 2. 生成 JS 包装器，处理 String 的 UTF-8 ↔ UTF-16 转换
// 3. 管理内存生命周期（创建的 JS 字符串会被正确释放）
#[wasm_bindgen]
pub fn greet(name: &str) -> String {
    format!("Hello, {}! 来自 Rust WASM", name)
}

// 暴露 Rust 结构体给 JS
#[wasm_bindgen]
pub struct Counter {
    count: i32,
}

#[wasm_bindgen]
impl Counter {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Counter {
        Counter { count: 0 }
    }

    pub fn tick(&mut self) {
        self.count += 1;
    }

    #[wasm_bindgen(getter)]
    pub fn count(&self) -> i32 {
        self.count
    }
}

# 进入项目目录
cd wasm-hello

# 构建为 Web 模块（默认输出到 pkg/）
wasm-pack build --target web

# 查看输出
ls pkg/
# pkg/
#   wasm_hello_bg.wasm      # 核心 WASM 二进制
#   wasm_hello_bg.js        # 胶水代码（JS 模块）
#   wasm_hello.js           # 公共 API 入口
#   package.json            # npm 包声明

# 在 React 项目中安装本地 WASM 模块
cd my-react-app
npm install ../wasm-hello/pkg

// App.tsx
import init, { greet, Counter } from 'wasm-hello';
import { useEffect, useState } from 'react';

function App() {
  const [message, setMessage] = useState('');

  useEffect(() => {
    // 对于 --target web，需要先调用 init() 加载 wasm 文件
    init('/node_modules/wasm-hello/wasm_hello_bg.wasm').then(() => {
      setMessage(greet('React'));
    });
  }, []);

  const handleClick = () => {
    const counter = new Counter();
    counter.tick();
    counter.tick();
    console.log(counter.count); // 2
  };

  return (
    <div>
      <h1>{message}</h1>
      <button onClick={handleClick}>Test Counter</button>
    </div>
  );
}

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    // 确保 .wasm 文件可以被正确加载
    fs: {
      allow: ['..'],
    },
  },
  // Vite 4+ 支持原生 WASM 导入
  optimizeDeps: {
    exclude: ['wasm-hello'],
  },
});

# 运行 wasm-pack 测试（Chrome headless，需要在 test 代码中用 wasm_bindgen_test）
wasm-pack test --headless --chrome

# 或在 Node 环境中测试
wasm-pack test --node

// tests/web.rs
use wasm_bindgen_test::*;
use wasm_hello::*;

wasm_bindgen_test_configure!(run_in_browser);

#[wasm_bindgen_test]
fn test_greet() {
    assert_eq!(greet("Test"), "Hello, Test! 来自 Rust WASM");
}

#[wasm_bindgen_test]
fn test_counter() {
    let mut counter = Counter::new();
    assert_eq!(counter.count(), 0);
    counter.tick();
    assert_eq!(counter.count(), 1);
}

[package]
name = "wasm-hello"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]  # 必须指定 cdylib，否则 wasm-pack 不识别

[profile.release]
opt-level = 3           # 最高优化级别
lto = true              # 链接时优化（跨模块内联）
codegen-units = 1       # 单 codegen unit，提高 LTO 效果
panic = "abort"         # 移除 panic 的栈展开支持，大幅减小体积
strip = true            # 移除调试符号

[dependencies]
wasm-bindgen = "0.2"
wee_alloc = { version = "0.4", optional = true }  # 小型分配器（约 1KB vs 默认 10KB+）

[features]
default = ["wee_alloc"]

# 安装 wasm-opt
npm install -g wasm-opt

# 在 wasm-pack build 后执行
wasm-opt -O3 -o pkg/wasm_hello_bg_opt.wasm pkg/wasm_hello_bg.wasm