Rust 开发 Wasm 踩坑记：从 0 到 1 的环境搭建全攻略

本系列记录我用 Rust 开发 WebAssembly 图像处理工具的完整踩坑历程。关键字: Rust, WebAssembly, wasm-pack, 环境配置

[[TOC]]

一、为什么选 Rust + Wasm？

在浏览器端实现图像实时滤镜处理。用 JavaScript 跑 4K 图像直接卡成 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

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

解决方案：

cargo install wasm-bindgen-cli --force

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

4.1 初始化前端项目

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

4.2 本地引用 wasm 包

安装生成的包：

npm install ../wasm-demo/pkg

修改 main.js：

import init, { greet } from 'wasm-demo';

async function run() {
  await init();
  const result = greet('Rust Wasm');
  console.log(result); // Hello, Rust Wasm!
  document.getElementById('app').innerHTML = result;
}

run();

4.3 配置 Vite

踩坑 #4：直接运行 npm run dev 报错

Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "application/wasm".

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

export default {
  optimizeDeps: {
    exclude: ['wasm-demo']
  },
  server: {
    headers: {
      'Content-Type': 'application/wasm'
    }
  }
}

五、完整验证：Hello World 最终版

Cargo.toml 最终配置：

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

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

[dependencies]
wasm-bindgen = "0.2"

[profile.release]
opt-level = 'z'  # 优化体积
lto = true

构建命令：

wasm-pack build --release --target web

前端完整代码：

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Wasm Demo</title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/main.js"></script>
</body>
</html>

// main.js
import init, { greet } from 'wasm-demo';

async function initWasm() {
  // 加载 wasm 文件
  await init();
  
  // 调用 Rust 函数
  const message = greet('习客港湾');
  document.getElementById('app').innerHTML = `
    <h1>${message}</h1>
    <p>Wasm 模块加载成功！</p>
  `;
}

initWasm().catch(console.error);

六、踩坑总结：血泪教训清单

问题现象	根本原因	解决方案
wasm-bindgen-CLI 下载失败	wasm-pack 内部下载机制	手动安装
MIME type 错误	Vite 默认配置问题	修改 vite.config.js
内存越界	未调用 `init()`	必须先初始化再调用函数

七、验证清单

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

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

Rust 开发 Wasm 实战：在浏览器中构建高性能图像处理工具 - 开发日志,Rust, WebAssembly, wasm-pack, 环境配置 - 本系列记录我用 Rust 开发 WebAssembly 图像处理工具的完整踩坑历程。