Rust 开发 Wasm 从 0 到 1 - 开发日志,Rust, WebAssembly, wasm-pack, 环境配置 - 本系列记录我用 Rust 开发 WebAssembly 从0到1的完整踩坑历程。

本系列记录我用 Rust 开发 WebAssembly 从0到1的完整踩坑历程。 关键字: Rust, WebAssembly, wasm-pack, 环境配置

一、为什么选 Rust + Wasm？

在浏览器端实现图像实时滤镜处理。用 JavaScript 跑大图直接卡成 PPT，Canvas GPU 加速又遇到兼容性问题。纠结之际，看到 Rust 可以编译成 Wasm 在浏览器运行，性能接近原生 C++，还能避免内存泄漏这种浏览器崩溃元凶。

二、环境搭建：理想 vs 现实

2.1 安装 Rust 工具链

相对新手而言，Rust的环境部署有点麻烦，不过别担心参考下 别浮躁！Rust环境搭建没有那么难

三、wasm-pack：万恶之源

3.1 安装 wasm-pack

官方文档说：

cargo install wasm-pack

验证安装：

wasm-pack --version
# wasm-pack 0.13.1

3.2 测试首个项目

创建项目：

cargo new --lib wasm-demo
cd wasm-demo

修改 Cargo.toml：

[package]
name = "wasm-demo"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
wasm-bindgen = "0.2.105"

修改 src/lib.rs：

extern crate wasm_bindgen;

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern {
    pub fn alert(s: &str);
}

#[wasm_bindgen]
pub fn greet(name: &str) {
    alert(&format!("Hello, {}!", name));
}

构建：

wasm-pack build

踩坑：构建时卡在 [INFO]: Installing wasm-bindgen...

解决方案：

cargo install wasm-bindgen-cli --force

原因: binaryen 是一个 Wasm 优化工具，wasm-pack 会默认调用它来减小 Wasm 体积并提升性能，但网络问题（如访问 GitHub 困难）可能导致下载失败。

解决方案：

• 主要是压缩体积可以再 cargo.toml 中增加 wasm-opt = false 禁用
• 手动下载文件，将解压出来的bin目录拷贝至cargo的bin目录下

四、让 Wasm 在浏览器里跑起来

4.1 初始化前端项目

npm create vite@latest wasm-host -- --template vue
cd wasm-host

4.2 本地引用 wasm 包

修改 main.js

import { createApp, markRaw } from "vue";
import "./style.css";
import App from "./App.vue";

// 立即初始化 Wasm，避免组件重复加载
import init from "wasm-demo";

// 将 Wasm 实例标记为非响应式
const wasmModule = await init();

const app = createApp(App);

// 全局注入，所有组件共享同一个 Wasm 实例
app.config.globalProperties.$wasm = markRaw({
  greet: wasmModule.greet,
  grayscale_zero_copy: wasmModule.grayscale_zero_copy,
});

app.mount("#app");

修改 App.vue 文件（关键代码）

// 导入wasm模块
const { greet } = getCurrentInstance().appContext.config.globalProperties.$wasm
onMounted(async () => {
  // 调用greet函数
  greet('XIKEW.COM')
})

4.3 配置 Vite

解决方案：在 vite.config.js 中添加配置：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  server: {
    fs: {
      // 允许访问项目根目录上一级的wasm-demo/pkg目录
      allow: ['..']
    }
  }
})

五、验证清单

如果你按照本文步骤操作，最终应该得到：

• wasm-pack --version 输出正确版本
• wasm-pack build 在 Rust 项目下执行成功
• pkg 目录生成 .wasm、.js、.d.ts 文件
• 浏览器控制台输出 "Hello, 习客港湾!"
• 页面正常显示消息，无报错