Rust × WebAssembly 项目脚手架详解

发布于:2025-08-01 ⋅ 阅读:(20) ⋅ 点赞:(0)

一、模板概览

模板 生成方式 核心用途 典型角色
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 publishwasm-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 库

  1. package.json 加入 "my-wasm-lib": "file:../my-wasm-lib/pkg"
  2. run npm install,即可获取本地编译产物
  3. 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 王者之路扬帆起航 🚀


网站公告

今日签到

点亮在社区的每一天
去签到