Rust × WebAssembly 项目脚手架详解
一、模板概览
| 模板 | 生成方式 | 核心用途 | 典型角色 |
|---|---|---|---|
| wasm-pack-template | cargo generate … | 把 Rust 代码 打包成 npm 库 | 「底层算法/组件」作者 |
| create-wasm-app | npm init wasm-app | 构建纯 JS/TS 项目，消费上面生成的 npm 包 | Web 前端/Node 服务 |
| rust-webpack-template | npm init rust-webpack | 自带 Webpack & rust-loader，前端与 Rust 热编译一体 | 同 repo 混合开发 |
一句话理解：
- wasm-pack-template 造轮子，输出 .wasm + JS 包装器
- create-wasm-app 装轮子，专注业务逻辑
- rust-webpack-template 把「造轮子 + 装轮子」合并到一个工程里，适合迅速原型
二、wasm-pack-template——“Rust → npm”的起点
1. 快速上手
cargo install cargo-generate # 若未安装
cargo generate \--git https://github.com/rustwasm/wasm-pack-template.git \--name my-wasm-lib
cd my-wasm-lib
wasm-pack build --release --target bundler
生成目录结构：
my-wasm-lib/
├── src/lib.rs # 写 Rust 逻辑
├── Cargo.toml
└── pkg/ # wasm-pack 输出：.wasm + JS 包装文件
2. 关键特性
wasm-bindgen已接入：#[wasm_bindgen]让 Rust 函数暴露给 JS- 测试与 CI 模板：开箱集成
wasm-bindgen-test、GitHub Action - TypeScript 类型声明：
pkg/*.d.ts自动生成，IDE 友好 - npm publish：
wasm-pack publish秒发 npm
3. 与 JS 项目联调
cd my-wasm-lib
npm link # 全局软链cd ../front-app
npm link my-wasm-lib
即可在前端代码里 import init, { foo } from 'my-wasm-lib'。
三、create-wasm-app——“JS 消费 wasm 库”的最佳拍档
1. 初始化
mkdir front-app && cd $_
npm init wasm-app # 交互式选择：JS / TS、打包工具等
npm install # 装依赖
npm run start # 本地 dev server，自动加载 .wasm
2. 项目亮点
- 零配置加载 wasm：脚手架已注入
init()+await处理 - 支持 TS：可直接
import type的 d.ts - vite / webpack / parcel 多框架可选（新版本）
3. 结合自研 wasm 库
- 在
package.json加入"my-wasm-lib": "file:../my-wasm-lib/pkg" - run
npm install，即可获取本地编译产物 import { add } from "my-wasm-lib";
四、rust-webpack-template——前后端一体化热编译
1. 生成项目
mkdir wasm-fullstack && cd $_
npm init rust-webpack
npm run start
默认结构：
src/lib.rs # Rust 入口
webpack.config.js
index.js # 前端逻辑，已 import './pkg'
2. 为什么选它
| 特性 | 说明 |
|---|---|
| 热更新 HMR | 改 Rust -> wasm-pack watch -> Webpack reload |
| rust-loader | Webpack loader 直接调用 wasm-pack build |
| 统一依赖 | npm install 即可管理前后端包 |
3. 适用场景
- 前端业务少、算法核心多，想要 改代码 ⇢ 浏览器秒刷新
- Hackathon / Demo 期望 5 分钟跑通
五、典型工作流组合
方案 A：代码分仓，产物 npm 依赖（推荐团队协作）
- wasm-lib 用 wasm-pack-template
- ui-app 用 create-wasm-app
- 优点：职责清晰，版本控制友好
方案 B：单仓库极速原型（个人项目）
- 一条
npm run start启动全栈 - 缺点：Rust 与 Node 依赖都塞在 package.json，后期拆分略麻烦
六、常见问题 FAQ
| 症状 | 解决方案 |
|---|---|
wasm-pack 提示 wasm32-unknown-unknown unavailable | rustup target add wasm32-unknown-unknown |
Module not found: rust-loader | 仅 rust-webpack-template 内置；其他脚手架请用 wasm-pack build 先产物 |
TypeError: WebAssembly.instantiate 跨域 | dev server 需启用 --headers 'Access-Control-Allow-Origin:*'，或改用 fetch('/pkg/pkg_bg.wasm') |
| IE11 报崩 | 用 wasm2js 转 asm.js 或选择降级方案 |
七、结语与实践建议
- 先选模板，再写业务：早期踩好脚手架能省掉 80% 配置工夫
- 生产环境请务必在 CI 流水线 跑
wasm-pack build --release+wasm-opt -Oz，体积可缩减 30-50% - 关注 rustwasm 工作组 的新模板，如基于 Vite / SWC 的现代版本
动手吧！ 五分钟复制下方命令，你的第一个 Rust → WebAssembly 项目，就此诞生！
# 1) 造轮子
cargo install cargo-generate wasm-pack
cargo generate --git https://github.com/rustwasm/wasm-pack-template.git --name my-wasm-lib
cd my-wasm-lib && wasm-pack build --release# 2) 装轮子
mkdir my-app && cd $_
npm init wasm-app
npm install ../my-wasm-lib/pkg # or `npm link`# 3) 运行
npm run start
祝编码愉快，WASM 王者之路扬帆起航 🚀