一、模板概览
模板 | 生成方式 | 核心用途 | 典型角色 |
---|---|---|---|
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 王者之路扬帆起航 🚀