前端Rust二进制/wasm全平台构建流程简述

前言

开门见山，现代前端 Rust 构建基本分三大类，即 构建 .wasm 、构建 .node 二进制 、构建 swc 插件。

入门详见 《 前端Rust开发WebAssembly与Swc插件快速入门 》 。

对于单独开发某一类的流程，在上述参考文章中已有介绍，但对于一次开发后全平台构建发布，上述文章并未涉猎，基于此，本文将快速介绍一个最简的 全平台构建 （包括二进制 .node 与 .wasm ） 前端 Rust 包的开发流程是怎样的。

注：我们默认读者已掌握构建三大类前端 Rust 包的知识。

正文

Rust workspace

以 workspace 组织代码仓库，核心逻辑全部独立为一个子包，参考如下：

 - crates- binding_node  # 基于 napi 分发 `.node` 二进制- binding_wasm  # 基于 wasm-pack 分发 `.wasm`- core          # 核心逻辑- ...           # 其他解耦

binding_node

其中 binding_node 为 node 构建出口，引用核心逻辑后暴露 API ，简式参考如下：

// binding_node/src/lib.rs#[macro_use]
extern crate napi_derive;use napi::{bindgen_prelude::AsyncTask, Env, Task};
use core::{core_process, IInput, IResult};// ⬇️ 同步部分
#[napi]
pub fn method_sync(input: IInput) -> Result<IResult, anyhow::Error> {core_process(input)
}// ⬇️ 异步部分
pub struct TaskExecutor {input: IInput,
}pub struct ProcessTask {task: TaskExecutor,
}impl Task for ProcessTask {type Output = IResult;type JsValue = IResult;fn compute(&mut self) -> napi::Result<Self::Output> {self.task.process().map_err(|err| napi::Error::from_reason(&err.to_string()))}fn resolve(&mut self, _env: Env, output: Self::Output) -> napi::Result<Self::JsValue> {Ok(output)}
}impl TaskExecutor {pub fn process(&self) -> Result<IResult, anyhow::Error> {core_process(self.input.clone())}
}#[napi(ts_return_type="Promise<IResult>")]
pub fn method(input: IInput) -> AsyncTask<ProcessTask> {AsyncTask::new(ProcessTask {task: TaskExecutor { input },})
}

注：此处为最简函数式示例，涉及 异步信号、错误处理、错误打印、导出多方法的复杂类 等情况时请自行处理。

通常情况提供最普通的 同步函数 方法已足够。

类型处理

为了尽可能减少工作量，让 napi 自动生成 .d.ts 类型，需给结构对象加上 #[napi] 宏才能生成类型，但所有结构声明在 crates/core 核心逻辑包中，而我们的 napi 出口在 crates/binding_node 。

一种解法是条件编译，提供 feature = "node" 的特定模式，参考如下：

# core/Cargo.toml[features]
default = []
node = ["napi", "napi-derive"][dependencies]
napi = { ..., optional = true }
napi-derive = { ..., optional = true }

// 条件编译宏#[macro_export]
#[cfg(feature = "node")]
macro_rules! multi_env {($($items:item)*) => {use napi_derive::napi;$(#[napi(object)]$items)*};
}

使用参考：

multi_env! {pub struct IInput {pub input: ...,}pub struct IResult {pub output: ...,}// ...
}

综上，通过特定 node feature 方式，在引用时条件添加 #[napi] 来做到自动生成类型。

人工应对复杂类型

如 想自行管理导出方法类型的暴露情况、涉及 class 等复杂的类型 、无法自动识别生成 等情况，可以人工编写整份 .d.ts 文件，但十分耗费精力。

对于 异步情况等 引发的动态值转换，而无法自动识别类型的，可尝试 napi 默认自带的类型选项，如 #[napi(ts_return_type="...")] 等选项来辅助修改生成的类型，省时省力。

构建

对于多平台，我们通常需要依赖 GitHub Actions 来进行多平台构建，在 CI 中构建、测试后发布到 npm 。

现代常用构建对象 napi 列表如下：

    "triples": {"defaults": false,"additional": ["x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc","aarch64-pc-windows-msvc","x86_64-unknown-linux-gnu","aarch64-unknown-linux-gnu","x86_64-unknown-linux-musl","aarch64-unknown-linux-musl"]},

最常用的即如上 8 个平台，酌情构建 armv7-unknown-linux-gnueabihf ，必要时采用 wasm 兜底即可。

此部分过于冗长且模板化，可参考 swc 等项目的构建 CI 来取用。

binding_wasm

其中 binding_wasm 为 wasm 构建出口，引用核心逻辑后暴露 API ，简式参考如下：

use wasm_bindgen::prelude::*;use core::{core_process, IInput, IResult};#[wasm_bindgen(js_name = "methodSync")]
pub fn method_sync(input: IInput) -> Result<IResult, JsError> {core_process(input).map_err(|err| JsError::new(&err.to_string()))
}#[wasm_bindgen(typescript_custom_section)]
const INTERFACE_DEFINITIONS: &'static str = r#"
export function method(config: IInput): Promise<IResult>;
"#;#[wasm_bindgen(skip_typescript)]
pub fn method(input: IInput) -> js_sys::Promise {wasm_bindgen_futures::future_to_promise(async {core_process(input).map(|r| serde_wasm_bindgen::to_value(&r).unwrap()).map_err(|err| JsValue::from_str(&err.to_string()))})
}

注：此处为最简函数式示例，涉及 异步、错误处理、错误打印 等情况时请自行修订处理。

通过 serde-wasm-bindgen 来动态转换 JS 值与 Rust 中的结构。

通常情况提供最普通的 同步函数 方法已足够。

类型处理

为了尽可能减少工作量，我们使用 tsify 做自动类型生成，同上文中相同，采用条件编译，提供 feature = "wasm" 模式：

# core/Cargo.toml[features]
default = []
wasm = ["tsify", "wasm-bindgen"][dependencies]
tsify = { ..., optional = true }
wasm-bindgen = { ..., optional = true}

// 条件编译宏#[macro_export]
#[cfg(feature = "wasm")]
macro_rules! multi_env {($($items:item)*) => {use tsify::Tsify;use serde::{Deserialize, Serialize};use wasm_bindgen::prelude::*;$(#[derive(Tsify, Serialize, Deserialize)]#[tsify(into_wasm_abi, from_wasm_abi)]$items)*};
}// 兜底用
#[macro_export]
#[cfg(all(not(feature = "wasm"), not(feature = "node"),))]
macro_rules! multi_env {($($tokens:tt)*) => {$($tokens)*};
}

人工应对复杂类型

如 想自行管理导出方法类型的暴露情况、无法自动识别生成 等情况，可以人工编写整份 .d.ts 文件。

对于 异步情况等 引发的动态值转换，而无法自动识别类型的，尝试 #[wasm_bindgen(skip_typescript)] 跳过自动生成类型后，使用 #[wasm_bindgen(typescript_custom_section)] 人工插入少量类型声明来解决，节省编写时间。

构建

由于 wasm 无需依赖本机环境，根据情况可选在云构建或本地构建均可，主要包含 web 用途与 nodejs 用途的 wasm 产物构建。

web 用途

web 用途的 wasm 产物主要用于网页应用，playground 等，构建命令参考：

  # web 用途cd crates/binding_wasm && wasm-pack build --verbose --out-dir ./output/wasm_web --out-name index --release

web 用途的构建产物包含 ESM 格式胶水代码 ，可直接将产物整体用在 webpack 项目导入，对于 webpack 5 可直接开启 async webassembly 特性直接适配项目：

// webpack.config.jsexperiments: {asyncWebAssembly: true,},

import * as wasm from '/path/to/wasm-output'
// 或使用异步 await import() 延时、按需加载

nodejs 用途

nodejs 用途主要用于非主流平台兜底，如 边缘函数、serverless 等环境，构建命令参考：

  # nodejs 用途cd crates/binding_wasm && wasm-pack build --target nodejs --verbose --out-dir ./output/wasm --out-name index --release

和 web 用途构建命令区别在于特定了 --target nodejs ，这会得到 CJS 格式产物代码，可直接用于 nodejs 。

使用与安装时机

对于两种 wasm 包，通常命名为 @scope/wasm （ nodejs 用途） 、@scope/wasm-web （ web 用途），在对应平台下，可直接安装该包来使用。

同时，对非主流架构环境，我们一般在主包的 postinstall 时进行脚本检测，并在需要时自动安装 @scope/wasm 包来兜底，具体逻辑较冗长且模板化，可参考 swc 等项目取用即可。

如何安装指定平台包

最新版本的 pnpm v8 支持配置 pnpm.supportedArchitectures 来安装想要的平台包，即使你不在某个平台上，这通常用于 wasm 安装校验：

# .npmrc
# 关闭 postinstall 缓存
side-effects-cache=false
# 打印 postinstall 日志
reporter=append-only

// package.json// ↓ 该配置将匹配不到任何 `.node` 的平台包，于是自动 fallback 到 wasm 兜底包"pnpm": {"supportedArchitectures": {"os": ["unknown"],"cpu": ["x64"]}}

wasm 产物优化

通常 .node 二进制产物由 Rust 生产构建后自动优化，加上 strip 优化体积已足够。

对于 wasm 一般采用 wasm-opt 优化体积，默认 wasm-pack 生产构建最终阶段会自动下载相关工具并执行优化，如遇网络问题，可关闭自动优化，转为手动下载后执行优化：

  # 提前下载好执行工具，防止网络问题cargo install wasm-bindgen-cli

# binding_wasm/Cargo.toml# 关闭 wasm-opt 自动优化，之后手动优化
[package.metadata.wasm-pack.profile.release]
wasm-opt = false

  # 下载 wasm-opt 工具并解压# 最新版本见：https://github.com/WebAssembly/binaryen/releasescurl -L https://github.com/WebAssembly/binaryen/releases/download/version_116/binaryen-version_116-x86_64-macos.tar.gz -o ./binaryen.tar.gzmkdir ./.cachetar -xvf ./binaryen.tar.gz -C ./.cache# 优化 wasm 产物./.cache/binaryen-version_116/bin/wasm-opt -Oz -o ./output/wasm/index_bg.wasm ./output/wasm/index_bg.wasm

总结

在全平台构建时，编写 十分大量 的人力脚本与文件操作在所难免，如有可能，可将其统一抽象化，方便下次取用。

由于流程更偏向于固定模板化，在实践时，请自行参考相关项目自取所需即可。