一、模板概览

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