Rust + WebAssembly 全链路解析

第20章设计模式与架构决策

作者杨艺韬 · 14,774 字 · 发布于 2026-04-25 · 更新于 2026-09-24

"There are no solutions, only trade-offs." — Thomas Sowell

前 19 章覆盖了 WASM 的规范、工具链、性能、服务器端、集成和可观测性——每章都在做"选择"：选择 wasm-bindgen 还是组件模型，选择 opt-level = "z" 还是 opt-level = 3，选择预分配还是按需分配。本章把这些散落在各章中的选择系统化为 12 条架构决策，每条决策给出选项、权衡和推荐。

12 条决策的排列顺序遵循从高层到低层的原则：先决定 WASM 在架构中的定位（全局性决策），再决定互操作方案和内存策略（架构性决策），最后决定构建配置和版本策略（工程性决策）。高层决策约束低层决策——例如，选择"计算引擎"定位自然导致 wasm-bindgen 互操作方案和句柄式 API 设计。

20.1 决策一：WASM 在架构中的定位

WASM 在软件架构中的定位决定了整个项目的技术路线——这是最高层级的决策，一旦确定很难逆转。

graph TD
  A{WASM 的角色?} --> B["计算引擎<br/>Compute Engine"]
  A --> C["UI 框架内核<br/>Framework Core"]
  A --> D["全栈应用<br/>Full-stack App"]
  B --> B1["JS 负责所有 UI<br/>WASM 只做计算<br/>✓ 最小侵入，渐进式引入<br/>✓ 团队不需要学 Rust<br/>✓ 适合 90% 的场景"]
  C --> C1["Rust/WASM 负责 UI<br/>Yew / Leptos<br/>✓ 类型安全端到端<br/>✓ SSR/SSG 统一<br/>✗ JS 生态不可用<br/>✗ 调试体验差"]
  D --> D1["同一份 Rust 代码<br/>浏览器 + 服务器<br/>✓ 代码复用最大化<br/>✓ 共享类型定义<br/>✗ 构建复杂度最高<br/>✗ 两套运行时行为差异"]
  style B fill:#10b981,color:#333
  style C fill:#f59e0b,color:#333
  style D fill:#6366f1,color:#fff

推荐：除非团队全栈 Rust 且愿意接受生态限制，否则选择"计算引擎"模式——在现有 JS 项目中引入 WASM 做性能热点，而不是用 Rust 重写整个前端。这是第 16 章的核心结论（§16.1、§16.8），第 19 章的前三个案例也都有这层分工：Figma 的编辑器内核与渲染器在 WASM 里，部分界面仍由 TypeScript + React 实现；图像管道只把像素计算交给 WASM，Canvas 仍由 JS 管；密码学模块只做算法与密钥保管，不碰扩展 UI。

三种定位的适用场景对比：

定位	典型项目	团队技能要求	生态依赖	推荐度
计算引擎	图像处理、密码学、数据分析、渲染引擎	Rust（后端）+ JS（前端）	最小	最推荐
UI 框架内核	内部工具、管理后台、技术探索	全栈 Rust	较大	谨慎选择
全栈应用	全 Rust 技术栈的产品、跨平台应用	全栈 Rust + 运维	最大	仅限特殊场景

"计算引擎"定位的核心优势是渐进式引入——不需要重写现有代码，只需要把性能瓶颈的函数替换为 WASM 实现。JS 团队的学习成本几乎为零——只是多了一个 npm 包的调用。这与《React 19 内核探秘》专栏第 18 章讨论的"渐进式迁移"理念一致——新技术的引入不应该要求重写现有系统。

20.2 决策二：互操作方案

WASM 模块必须与宿主交互——选择哪种互操作方案决定了 API 的表达能力和可移植性。

方案	适用场景	优势	劣势	章节参考
`wasm-bindgen`	浏览器，Rust ↔ JS	成熟、类型安全、自动 TS 声明	只支持 Rust ↔ JS，绑定代码增加体积	第 6 章
组件模型 + `wit-bindgen`	服务器/边缘，多语言互操作	语言无关、在 W3C WebAssembly 社区组/Bytecode Alliance 下推进标准化、IDL 定义清晰	浏览器尚无原生支持、工具链仍在演进	第 14-15 章
Extism	插件系统，简单接口	极简 API、多语言宿主、PDK 封装	类型安全弱、只支持字节传递、扩展性受限	第 17 章
嵌入 Wasmtime	自定义运行时需求	最大灵活性、可自定义所有行为	实现复杂、需要深入 Wasmtime API	第 17 章

推荐：浏览器用 wasm-bindgen，服务器/插件用组件模型，简单插件用 Extism。一个项目可能同时使用两种方案——浏览器端用 wasm-bindgen，服务器端用组件模型，共用核心逻辑通过 cfg(target_os) 条件编译切换。

graph TD
  A{宿主环境?} --> B["浏览器"]
  A --> C["服务器/边缘"]
  A --> D["插件系统"]
  B --> E["wasm-bindgen<br/>+ web-sys<br/>✓ 成熟稳定<br/>✓ TS 声明自动生成"]
  C --> F["组件模型<br/>+ wit-bindgen<br/>✓ 多语言互操作<br/>✓ 标准化推进中"]
  D --> G{复杂度?}
  G -->|简单接口| H["Extism<br/>✓ 接入代码少"]
  G -->|复杂接口| F
  style E fill:#10b981,color:#333
  style F fill:#6366f1,color:#fff
  style H fill:#f59e0b,color:#333

选择互操作方案时，除了考虑宿主环境，还要考虑 API 的稳定性需求。wasm-bindgen 的绑定代码是自动生成的——每次 wasm-bindgen 版本升级或 #[wasm_bindgen] 签名变更，生成的 JS 胶水代码都可能变化。组件模型的 WIT 接口定义是稳定的——接口变更需要显式的版本升级，不会因为工具链升级而意外破坏。

20.3 决策三：内存分配策略

WASM 的内存分配策略直接影响性能和可预测性。第 10 章分析了内存分配的性能影响，第 19.2 节则用 Processor 让图像数据常驻线性内存、实测了省掉胶水复制的效果。

三种策略的代码对比

// 策略一：按需分配——每次调用分配新内存
#[wasm_bindgen]
pub fn process(data: &[u8]) -> Vec<u8> {
    let mut output = Vec::new(); // 每次调用分配
    // ... 处理 ...
    output
}

// 策略二：预分配——重用缓冲区
#[wasm_bindgen]
pub struct Processor {
    buffer: Vec<u8>,
    scratch: Vec<u8>,  // 临时缓冲区也预分配
}

#[wasm_bindgen]
impl Processor {
    pub fn process(&mut self, data: &[u8]) {
        self.buffer.clear();
        self.scratch.clear();
        // ... 处理到 self.buffer ...
    }

    // 导出方法不能返回借用（写 -> &[u8] 会报
    // "cannot return a borrowed ref with #[wasm_bindgen]"），
    // 改为交出指针与长度，JS 在 memory.buffer 上建视图读取（§19.2 同款）
    pub fn output_ptr(&self) -> *const u8 { self.buffer.as_ptr() }
    pub fn output_len(&self) -> usize { self.buffer.len() }
}

// 策略三：无分配——纯栈上计算
// 注意 #![no_std] 是内部属性，只能写在 crate 根（src/lib.rs 首行），不是这里
#[wasm_bindgen]
pub fn compute_hash(data: &[u8]) -> u64 {
    // 函数体内的中间数据都在栈上——不调用 allocator
    // （但 &[u8] 参数本身仍由胶水经 __wbindgen_malloc 复制进线性内存）
    let mut state: [u64; 8] = [0; 8]; // 固定大小的栈数组
    // ... FNV / SipHash ...
    state[0]
}

策略	适用场景	优势	劣势	典型应用
按需分配	低频调用、数据量小、一次性工具	代码简单、无状态	每次分配/释放有开销、可能触发 `memory.grow`，返回的 `Vec` 还要在 JS 侧新建数组	配置解析、一次性转换
预分配	高频调用、数据量固定、长生命周期	零分配开销、可预测延迟	需要管理 Processor 生命周期	图像处理、密码学、渲染
无分配	纯计算、无堆需求、极致体积	零分配开销、最小体积	受限于栈上数据（这两条都写在 `compiler/rustc_target/src/spec/base/wasm.rs` 里：14 行的 `stack-size=1048576` 定下 1MB 默认栈，30 行的 `--stack-first` 把栈放到静态数据之前，源码注释说明这样做是为了让栈溢出必然以下溢 trap 收场，而不是静默改写静态数据）	哈希计算、位操作

推荐：高频调用用预分配，一次性调用用按需分配，纯计算用无分配写法（体积敏感时再配 #![no_std]）。第 19.2 节的图像管道实测给了这件事一个清醒的量级：改用 Processor 模式后胶水不再替切片参数做 malloc 加来回复制，只剩 JS→WASM、WASM→JS 各一次显式的 set（33MB 单次约 5ms），但在那个灰度负载里计算本身（约 44ms）才是大头——预分配省的是固定开销，不能替代对计算的测量。预分配的关键实现细节是 Processor 必须是一个 #[wasm_bindgen] 结构体——JS 侧持有它的引用，确保 Rust 侧的缓冲区在多次调用之间不被释放。

预分配的陷阱

预分配不是没有风险。最大的陷阱是内存膨胀——如果 Processor 的缓冲区预分配过大（比如 4K 图像的 33MB），即使实际只处理小图像，这 33MB 也不会被释放。在浏览器环境中，多个 Processor 实例可能同时存在，导致内存使用量远超实际需求。

解决方案：分级预分配——初始分配较小缓冲区，处理大图像时才扩展：

#[wasm_bindgen]
pub struct Processor {
    buffer: Vec<u8>,
    capacity: usize,  // 当前缓冲区容量
    max_capacity: usize,  // 允许的最大容量
}

impl Processor {
    fn ensure_capacity(&mut self, needed: usize) {
        // 超过上限就拒绝——否则下面 min() 会给出比 needed 还小的缓冲区
        assert!(needed <= self.max_capacity, "input exceeds max_capacity");
        if needed > self.capacity {
            let new_capacity = needed.next_power_of_two().min(self.max_capacity);
            self.buffer.resize(new_capacity, 0);
            self.capacity = new_capacity;
        }
    }
}

20.4 决策四：错误处理策略

WASM 的错误处理有三个层次：Rust 的 Result<T, E>、WASM 的 trap、JS 的 Error。选择哪种策略取决于对可观测性（第 18 章）和体积的要求。

// 策略一：Result + JsValue（推荐——兼顾可观测性和体积）
#[wasm_bindgen]
pub fn process(data: &[u8]) -> Result<Vec<u8>, JsValue> {
    if data.is_empty() {
        // JS 侧 catch 到的是一个字符串而不是 Error（没有 stack）；
        // 需要 Error 对象时写 Err(js_sys::Error::new("empty input").into())
        return Err(JsValue::from_str("empty input"));
    }
    Ok(try_process(data)?) // try_process 返回 Result<Vec<u8>, E>，要求 JsValue: From<E>
}

// 策略二：panic = abort + unwrap（简单但不可观测）
#[wasm_bindgen]
pub fn process(data: &[u8]) -> Vec<u8> {
    assert!(!data.is_empty(), "empty input");
    do_process(data) // 内部用 unwrap，出错直接 trap
}

// 策略三：catch_unwind 包装——在 wasm32-unknown-unknown 等默认 abort 的目标上无效，仅作对照
#[wasm_bindgen]
pub fn safe_process(data: &[u8]) -> Result<Vec<u8>, JsValue> {
    std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| do_process(data)))
        .map_err(|e| JsValue::from_str(&format!("panic: {:?}", e)))
}

三种策略的对比：

策略	可观测性	体积影响	性能影响	panic=abort 兼容
`Result<T, JsValue>`	高——错误消息传回 JS	无	轻微（分支预测）	兼容
`panic = abort` + unwrap	低——不装 panic hook 时，浏览器里 JS 只拿到 `RuntimeError: unreachable`（V8）	最小	无	本身就是 abort
`catch_unwind`	默认工具链下无效——panic 直接 abort	无（abort 下不生成 unwind 表）	无	不兼容

推荐：公开 API 用 Result<T, JsValue>（策略一），内部实现用 unwrap/expect + panic::set_hook（第 18.7 节的方案）。catch_unwind 在默认工具链下捕获不到任何东西，原因在目标定义：走 wasm 公共基线的目标（wasm32-unknown-emscripten 例外）一律是 panic_strategy: PanicStrategy::Abort（compiler/rustc_target/src/spec/base/wasm.rs:68），Rustup 分发的预编译 std 也是按 -Cpanic=abort 构建的。

但这不等于"WASM 永远不能 unwind"——rustc 的平台文档写明异常处理提案自 2025 年中已经稳定，该文档（src/doc/rustc/src/platform-support/wasm32-unknown-unknown.md 的 Unwinding 一节）给出了在 wasm 上打开 unwind 的完整步骤：nightly + -Zbuild-std 重新编译标准库，再加上 -Cpanic=unwind 和 -Cllvm-args=-wasm-use-legacy-eh=false。只是这条路目前既要 nightly 又要自建 std，不是生产默认；所以在稳定工具链上仍然不要把 catch_unwind 当兜底手段。

Result<T, JsValue> 的一个实践技巧是定义项目级错误类型，统一转换为 JsValue：

#[derive(Debug, thiserror::Error)]
enum ProcessingError {
    #[error("empty input")]
    EmptyInput,
    #[error("invalid format: {0}")]
    InvalidFormat(String),
    #[error("processing failed: {0}")]
    Internal(#[from] InternalError),
}

impl From<ProcessingError> for JsValue {
    fn from(e: ProcessingError) -> JsValue {
        JsValue::from_str(&e.to_string())
    }
}

#[wasm_bindgen]
pub fn process(data: &[u8]) -> Result<Vec<u8>, JsValue> {
    if data.is_empty() {
        return Err(ProcessingError::EmptyInput.into());
    }
    Ok(do_process(data)?)
}

这样错误消息在 Rust 侧有类型安全的定义，在 JS 侧统一为字符串——兼顾了两端的开发体验。

20.5 决策五：线程与并发

WASM 的线程模型仍不成熟——SharedArrayBuffer 需要特殊 HTTP 头（COOP/COEP），Web Worker 通信开销大，wasm-bindgen-rayon 的浏览器支持不一致。

graph TD
  A{并行需求?} --> B["无需并行<br/>(大多数场景)"]
  A --> C["CPU 密集型并行"]
  A --> D["需要共享状态的并行"]
  B --> E["单线程<br/>✓ 简单可靠<br/>✓ 所有浏览器支持"]
  C --> F["Web Worker<br/>+ comlink/wasm-bindgen-rayon<br/>✓ 利用多核<br/>✗ 通信开销<br/>✗ 需要消息传递架构"]
  D --> G["SharedArrayBuffer<br/>+ Atomics<br/>✓ 避免数据复制<br/>✗ 需要 COOP/COEP 头<br/>✗ 未跨源隔离时不可用"]
  style E fill:#10b981,color:#333
  style F fill:#f59e0b,color:#333
  style G fill:#dc2626,color:#fff

方案	适用场景	优势	劣势
单线程	大多数场景	简单可靠，无浏览器兼容问题	无法利用多核，长计算阻塞 UI
Web Worker	CPU 密集型并行	利用多核，不阻塞 UI	`postMessage` 要序列化/结构化克隆，大对象尤其贵；无共享状态
SharedArrayBuffer	需要共享状态的并行	避免数据复制	浏览器支持受限（需 COOP/COEP）

推荐：默认单线程。需要并行时用 Web Worker + comlink（简化 Worker 通信）或 wasm-bindgen-rayon（自动数据并行；它依赖 +atomics，在 Rust 1.96 上仍要 nightly 加 -Zbuild-std 重编 std，见 §10.9）——但要做好浏览器兼容性降级。用 SharedArrayBuffer 需要服务器端配置 COOP/COEP 响应头——《Axum 设计与实现》专栏第 22 章讨论的中间件栈与 SetResponseHeaderLayer 响应头设置同样适用于此场景。

降级策略是必要的——因为 SharedArrayBuffer 的可用性取决于服务器配置和浏览器策略。Spectre 之后各家浏览器都把 SharedArrayBuffer 收在跨源隔离（cross-origin isolation）之后——MDN 的 SharedArrayBuffer 条目写明它要求文档处于安全上下文且已跨源隔离，并把这套新方案齐备的时间标在 2021 年 12 月（对应 Safari 15.2）。也就是说，没有正确的响应头就没有 SharedArrayBuffer，而不是"某些浏览器不支持"；此外某些企业浏览器策略也会直接禁用：

const hasSharedArrayBuffer = typeof SharedArrayBuffer !== 'undefined';
const isCrossOriginIsolated = window.crossOriginIsolated;

if (hasSharedArrayBuffer && isCrossOriginIsolated) {
  initMultithreadWasm();
} else {
  console.warn('SharedArrayBuffer not available, falling back to single-thread');
  initSingleThreadWasm();
}

20.6 决策六：构建目标选择

WASM 有两个主要构建目标：wasm32-unknown-unknown（浏览器）和 wasm32-wasip2（WASI Preview 2，服务器端）。选择取决于部署环境。

目标	适用场景	互操作方案	标准库支持
`wasm32-unknown-unknown` + `wasm-bindgen`	浏览器	`wasm-bindgen`	`std` 可用，但无 I/O
`wasm32-wasip2` + `wit-bindgen`	支持组件模型的 WASI 运行时（首选 Wasmtime，见 §17.8）	组件模型 + WIT	`std` + WASI API
两者都编译	全栈应用	按条件编译切换	分别配置

全栈编译的 Cargo.toml 配置：

[lib]
crate-type = ["cdylib", "lib"]

# 浏览器特有的依赖
[target.'cfg(all(target_arch = "wasm32", target_os = "unknown"))'.dependencies]
wasm-bindgen = "0.2"
web-sys = { version = "0.3", features = ["Window", "Performance"] }
js-sys = "0.3"

# WASI 特有的依赖（下面的 wasi 模块用 wit-bindgen 生成绑定）
[target.'cfg(all(target_arch = "wasm32", target_os = "wasi"))'.dependencies]
wit-bindgen = "0.57"

# 原生平台的依赖（用于本地测试）
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
tokio = { version = "1", features = ["full"] }

条件编译的代码组织——把核心逻辑与平台 API 分离：

// src/lib.rs — 公共 API
pub fn process(data: &[u8]) -> Vec<u8> {
    core_process(data) // 核心逻辑——所有平台共享
}

fn core_process(data: &[u8]) -> Vec<u8> {
    // 不依赖任何平台 API 的纯计算逻辑
    // 这个函数在所有平台上行为一致
    // 70% 的测试应该覆盖这个函数
    todo!()
}

// 浏览器特有的 API（这里内联写在 lib.rs，项目大了可拆成 browser.rs）
#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
mod browser {
    use wasm_bindgen::prelude::*;

    #[wasm_bindgen]
    pub fn process(data: &[u8]) -> Vec<u8> {
        super::process(data)
    }
}

// WASI 特有的 API（同上，可拆成 wasi.rs）
#[cfg(all(target_arch = "wasm32", target_os = "wasi"))]
mod wasi {
    // generate! 的参数是一个 { key: value } 结构，world 用字符串指定；
    // 默认从 crate 根的 wit/ 目录找 WIT，wasi:http 及其依赖包要放进 wit/deps/。
    // world 来自依赖包时，其余接口要么逐个写 with 映射，要么加 generate_all
    wit_bindgen::generate!({ world: "wasi:http/proxy", generate_all });

    use exports::wasi::http::incoming_handler::Guest;
    use wasi::http::types::{IncomingRequest, ResponseOutparam};

    struct Component;

    impl Guest for Component {
        // wasi:http/incoming-handler 的 handle 没有返回值——
        // 响应通过第二个参数 response-outparam 的 set 方法发出，
        // 这样才能边发响应边继续往 body 里流式写入
        // （read_body / send_response 是读写 body 的辅助函数，此处省略）
        fn handle(request: IncomingRequest, response_out: ResponseOutparam) {
            let result = super::process(&read_body(request));
            send_response(response_out, result);
        }
    }

    // export! 声明由 Component 提供 world 的导出
    export!(Component);
}

这种组织方式的关键原则：核心逻辑不知道自己在 WASM 中运行——它只是普通的 Rust 代码，可以在 cargo test 中直接测试。平台适配层（browser、wasi 两个模块）是薄薄的一层胶水，只负责调用核心逻辑和转换数据格式。

20.7 决策七：体积 vs 性能的平衡点

第 9 章详细分析了体积优化，这里从"决策"角度总结。体积和性能不是线性权衡——存在几个关键拐点。

graph LR
  subgraph "优化级别与体积（相对关系，绝对比例因项目而异）"
    A["opt-level = 3<br/>最大速度<br/>体积最大"] --> B["opt-level = 2<br/>平衡"]
    B --> C["opt-level = 's'<br/>偏体积"]
    C --> D["opt-level = 'z'<br/>最小体积<br/>可能牺牲热循环速度"]
  end
  subgraph "选择依据"
    E["选 3 的条件"] --- F["计算密集<br/>热循环占主导<br/>体积增大仍可接受"]
    G["选 'z' 的条件"] --- H["首屏加载关键<br/>体积已拖慢加载<br/>计算占比低"]
  end
  style A fill:#dc2626,color:#fff
  style D fill:#10b981,color:#333
  style C fill:#f59e0b,color:#333

推荐：默认 opt-level = "z" + LTO + panic = "abort" + strip = "debuginfo"（别写 strip = true：它连 target_features 段一起删掉，wasm-pack 默认跑的 wasm-opt 随之验证失败，见 §8.2 与 §9.3.5）。只有 profiling 证明某个热循环确实需要时，才为它单独提高优化级别。

函数级的优化级别在 Rust 里对应 #[optimize(...)] 属性——注意它至今仍是未稳定特性，只能在 nightly 上配合 #![feature(optimize_attribute)] 使用：

#![feature(optimize_attribute)] // nightly only

#[optimize(size)] // 跟随全局的体积优先策略
pub fn process(data: &[u8]) -> Vec<u8> {
    let result = hot_path_computation(data);
    post_process(result)
}

#[optimize(speed)] // 覆盖全局默认——这个函数要最大速度
fn hot_path_computation(data: &[u8]) -> Vec<u8> {
    // 这里才是真正的 CPU 热点：SIMD 循环、密集计算
    todo!()
}

"未稳定"这一条是可以直接查证的：compiler/rustc_feature/src/unstable.rs:634 把 optimize_attribute 登记为 unstable（自 1.34.0 起，跟踪 issue #54882），compiler/rustc_feature/src/builtin_attrs.rs:852 则把 optimize 属性本身标成 experimental。

在稳定版上，能做到的替代方案是把热点拆成独立 crate 单独设 profile（[profile.release.package.hot-kernel] opt-level = 3），或者干脆接受全局一个级别。

这种"全局体积优化 + 局部速度优化"的组合，适合热点代码在总量中占比很小的项目：体积代价只落在那一小块内核上。它划不划算取决于项目，需要自己测——第 19.2 节的实测就是提醒：那个灰度内核即便全程 opt-level = 3，也没跑赢 V8 优化后的 JS。

体积优化的另一个维度是依赖裁剪。量产物用 twiggy top 列出每个函数/段的体积占比（cargo bloat 只认 ELF/Mach-O/PE，不支持 WASM，见 §9.6.1）——体积往往集中在少数几个函数和依赖上。最常见的体积大户是：格式化代码（std::fmt）、泛型单态化（每个具体类型生成一份代码）、panic 处理（每个 unwrap 生成一段错误消息）。LTO 消除了未使用的泛型实例，去掉 format!/Debug 能砍掉 core::fmt——具体比例要用 twiggy 和实际产物大小去量，不要照抄别人的百分比。

20.8 决策八：调试 vs Release 构建

WASM 项目的构建配置比原生 Rust 项目更复杂——完全不优化的 WASM 运行起来很慢（引擎照样把它编译成机器码，慢在 rustc 没做任何优化的代码本身），需要三 profile 策略。

[profile.dev]
panic = "abort"           # wasm 目标默认就是 abort，写上只是把默认值写明
opt-level = 1             # 开发用轻度优化——未优化的 WASM 慢得没法用
debug = 1                 # 只保留行号信息——不保留变量名（减小体积）

[profile.release]
panic = "abort"           # wasm 目标默认就是 abort，写上只是把默认值写明（§9.3.1）
opt-level = "z"           # 最小体积
lto = true                # 跨 crate 优化——消除未使用代码
codegen-units = 1         # 单 codegen unit——更好的优化（编译更慢）
strip = "debuginfo"       # 只剥调试信息；别写 true——会删掉 target_features 段，
                          # wasm-pack 默认跑的 wasm-opt 随之验证失败（§8.2、§9.3.5）

[profile.profiling]       # 用 cargo build --profile profiling 构建；wasm-pack 的用法见表后
inherits = "release"      # 继承 release 的优化级别
debug = true              # 保留调试信息用于性能分析（Cargo 的键名是 debug，没有 debug_info）
strip = false             # 什么都不剥
# 注意：wasm 目标的 panic 策略默认就是 abort，这里写 panic = "unwind"
# 也不会生效——真要 unwind 得走 -Zbuild-std 那条路（见 §20.4），
# 所以默认配置下 catch_unwind 依然捕获不到（§18.7）

三个 profile 的使用场景：

Profile	何时使用	体积	速度	调试能力
`dev`	日常开发、功能验证	大	慢（但可接受）	行号级
`profiling`	性能分析、瓶颈定位	中（比 release 大，多出调试段）	与 release 相同（同一套优化）	源码级（DWARF，需 wasm-bindgen 与 wasm-opt 都保留，见下）
`release`	生产发布	最小	由 opt-level 决定	基本无（wasm-pack 默认的 `wasm-opt -O` 连名称段也丢）

为什么 dev 用 opt-level = 1 而不是 0？opt-level = 0 的 Rust 会生成大量未内联的小函数、把每个借用都老老实实落到内存。本专栏拿第 19.2 节那个 4K 灰度循环在 Wasmtime 44 上实测（Rust 1.96.0、wasm32-wasip1，dev profile 关掉 debug-assertions 与 overflow-checks，5 次取最快）：opt-level = 0 约 259ms，opt-level = 1 约 38ms，opt-level = 3 约 37ms——从 0 到 1 快了约 7 倍，从 1 到 3 几乎没有差别。opt-level = 1 是"最小可行优化"：运行速度已回到可用区间。常见的一种误判是"Rust 编译到 WASM 后比 JS 还慢"，一查才发现是拿 dev 构建在跟 JS 的生产代码比。

用 wasm-pack 构建时要注意，wasm-pack build --profiling 不会用上面这个 [profile.profiling]：wasm-pack 0.14.0 的 src/build/mod.rs:94-100 在 Profiling 分支给 cargo 传的就是 --release（设 RUSTFLAGS=-g 的那行被注释掉了），它只从 [package.metadata.wasm-pack.profile.profiling] 读 wasm-bindgen / wasm-opt 的参数。要用 Cargo 的 [profile.profiling]，得 wasm-pack build --profile profiling——这时走的是自定义 profile 分支，wasm-pack 读的是 [package.metadata.wasm-pack.profile.custom]（src/manifest/mod.rs:539）。而且四个内置配置的 dwarf-debug-info 默认都是 false（wasm-bindgen 不带 --keep-debug 就会剥掉 DWARF），wasm-opt 默认只传 -O、不带 -g 时连名称段也丢掉，所以要在对应的表里显式写上：

[package.metadata.wasm-pack.profile.custom]
wasm-opt = ["-O", "-g"]            # 保留名称段与调试信息

[package.metadata.wasm-pack.profile.custom.wasm-bindgen]
dwarf-debug-info = true            # 给 wasm-bindgen 传 --keep-debug

三 profile 策略与第 18 章的可观测性方案紧密相关（§18.5）：Performance 面板里显示 Rust 函数名而不是 wasm-function[42]，靠的是 .wasm 保留的名称段，不需要 DWARF；DWARF 再配上 Chrome 的 C/C++ DevTools Support (DWARF) 扩展，带来的是 Sources 面板里按 .rs 文件下断点、看变量的源码级调试。但 catch_unwind 在任何 profile 下都指望不上——wasm 目标的默认 panic 策略是 abort，而 profile 里的 panic 键改不了预编译 std 的构建方式（要改得按 §20.4 那套 -Zbuild-std 流程来，不是调 profile 能解决的）。所以无论哪个构建，panic 的可观测性都得靠 panic::set_hook 和结构化日志。

20.9 决策九：依赖管理

WASM 项目对依赖的选择比原生项目更挑剔——每个依赖都增加 .wasm 体积，而体积直接影响加载时间。第 9 章分析了体积优化技术，这里从"依赖选择"角度补充。

常见依赖的 WASM 适配情况

下表的"体积影响"一栏刻意不给绝对数字——同一个 crate 在不同 feature 组合、不同调用面下的体积能差好几倍，必须自己在产物上用 twiggy 量：

依赖	在 WASM 项目里的状况	替代方案
`serde` (+ `serde_json`)	可用，但序列化代码会被单态化放大	`serde-json-core`（`no_std`，功能子集）；或干脆让 JS 侧做 JSON，WASM 只收字节
`regex`	可用但很重（DFA 表 + Unicode 表）	关掉 `unicode` 相关 feature；手写匹配；或把正则逻辑留在 JS 侧
`chrono`	可用但偏重，且时区数据在 WASM 里意义不大	`js_sys::Date`（浏览器）或 `wasi:clocks`（WASI）
`reqwest`	浏览器目标可用——它有一套基于 `fetch` 的 wasm32-unknown-unknown 后端，但只覆盖部分 API（连接池、代理这类概念在 fetch 之上并不存在）；WASI 目标不可用	直接用 `web_sys` 的 fetch（浏览器）或 `wasi:http`（WASI）
`rand`	可用，但 `wasm32-unknown-unknown` 上必须显式给 `getrandom` 选熵源后端，否则编译期就被 `compile_error!` 挡下（不是链接期）——getrandom 0.3.4（2025-10-14）起只需开 `wasm_js` feature，0.4 系列同样如此；0.3.0–0.3.3 还得再加 `RUSTFLAGS='--cfg getrandom_backend="wasm_js"'`，0.2 系列则是 `js` feature（以 getrandom CHANGELOG 为准），见 getrandom 文档的 WebAssembly support 一节	浏览器走 `crypto.getRandomValues`，WASI 走 `wasi:random`
`tokio`	部分可用——不开 `tokio_unstable` 时 wasm 上只支持 `sync`、`macros`、`io-util`、`rt`、`time` 五个 feature，开别的（包括 `full`）直接编译失败；`time` 在没有计时器的 wasm32-unknown-unknown 上一调用就 panic（tokio 1.53 crate 文档的 WASM support 一节）	浏览器用 `wasm-bindgen-futures` 把 `Future` 接到微任务队列上
`clap`	能编过，但浏览器里没有 argv 这个概念	JS 侧解析参数后传给 WASM；WASI 命令行组件则正常可用

依赖审查流程

flowchart TD
  A["考虑引入依赖 X"] --> B{"X 支持 WASM 吗?"}
  B -->|否| C["寻找替代方案<br/>或把功能移到 JS 侧"]
  B -->|是| D["twiggy top 量产物体积"]
  D --> E{"体积增量可接受?"}
  E -->|是| F["引入"]
  E -->|否| G{"有更轻量的替代?"}
  G -->|是| H["使用替代方案"]
  G -->|否| I{"功能价值 > 体积成本?"}
  I -->|是| J["引入，在 Cargo.toml 中注释体积影响"]
  I -->|否| K["不引入"]
  style F fill:#10b981,color:#333
  style J fill:#f59e0b,color:#333
  style K fill:#dc2626,color:#fff

推荐：在引入每个依赖前，用 twiggy top 在 .wasm 产物上量一遍它的体积影响，并把量到的数字连同测量日期写进 Cargo.toml 的注释——版本一升，这个数字就可能失效：

[dependencies]
# 引入前后 .wasm 增量：自行测量后记在这里（含 feature 组合与测量日期）
serde = { version = "1", default-features = false, features = ["derive", "alloc"] }

# no_std 的轻量替代：功能是 serde_json 的子集，够用就别上完整版
serde-json-core = "0.6"

# 只在原生测试里用，不进 WASM 产物
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
regex = "1"

一个经常被忽略的体积优化是 default-features = false。很多 crate 的默认 feature 包含了 WASM 用不上的东西——例如 serde 默认开 std，而 no_std 场景用 default-features = false, features = ["derive", "alloc"] 就够。单个 crate 省下的可能只有几 KB，但依赖树一深就会累积，而且这种删减是零风险的：删掉的是根本没被调用的代码。

20.10 决策十：API 设计原则

WASM API 的设计原则与原生 Rust API 有本质区别——核心约束是"跨边界调用的成本远高于 WASM 内部调用"。第 11 章分析了数据传递的性能影响，这里从 API 设计角度总结三条原则。

原则一：最小化跨边界调用

每次从 JS 调用 WASM 函数（或反过来）都有一笔固定开销：参数转换 + 栈帧切换 + 返回值转换。按 §10.5 的实测，一次 (i32) -> i32 的跨边界调用约 5 ns，属于个位数纳秒——单次微不足道，但它不随数据量摊薄，调用次数一多就会主导整个耗时。对于需要频繁访问的属性，批量返回优于逐个访问：

// 反模式：粒度太细——每次属性访问都是跨边界调用
#[wasm_bindgen]
impl Config {
    pub fn get_width(&self) -> u32 { self.width }
    pub fn get_height(&self) -> u32 { self.height }
    pub fn get_format(&self) -> String { self.format.clone() }
    pub fn get_quality(&self) -> u32 { self.quality }
}
// 4 次跨边界调用；而且 get_format 每次都要新建一个 JS 字符串，
// 它比另外三个整数 getter 加起来还贵

// 正确模式：批量返回——一次跨边界调用
#[wasm_bindgen]
impl Config {
    pub fn to_json(&self) -> String {
        serde_json::json!({
            "width": self.width,
            "height": self.height,
            "format": self.format,
            "quality": self.quality,
        }).to_string()
    }
}
// 1 次跨边界调用——但代价是多了一次 JSON 序列化 + 一次字符串编解码，
// 字段少的时候未必划算，字段多、访问频繁时才明显占优

原则二：用句柄而非数据

对于敏感数据（密钥、文件描述符）或大数据（图像、音视频缓冲区），传递句柄（整数索引）而非数据本身：

// 反模式：每次传密钥数据——安全隐患 + 复制开销
#[wasm_bindgen]
pub fn encrypt(key_data: &[u8], plaintext: &[u8]) -> Vec<u8> { ... }
// key_data 从 JS 复制到 WASM——密钥短暂暴露在 JS 堆中

// 正确模式：传句柄——密钥只在 WASM 内存中
#[wasm_bindgen]
pub struct KeyHandle { inner: AeadKey }

#[wasm_bindgen]
impl KeyHandle {
    pub fn encrypt(&self, plaintext: &[u8]) -> Vec<u8> { ... }
}
// JS 只持有 KeyHandle 对象（内部是指向 WASM 内存的指针）——密钥不进 JS 堆

这是第 19.3 节参考设计（以 1Password 扩展为原型，不是 1Password 公开的实现）采用的方案——密钥句柄只是一个整数索引，JS 侧的日志、序列化拿到的只是这个索引。边界也要说清：同一 JS 环境里的代码仍能通过导出的 memory 读整块线性内存，也能拿着句柄调 encrypt，所以它缩小的是意外泄漏面，挡不住已拿到页面执行权的 XSS。句柄模式不仅适用于密钥——任何"数据只在 WASM 侧有意义"的场景都可以使用：数据库连接句柄、文件描述符、GPU 缓冲区引用。

原则三：避免 `JsValue` 在公共 API 中

// 反模式：JsValue 是类型黑洞——调用者不知道期望什么
#[wasm_bindgen]
pub fn process(input: JsValue) -> JsValue { ... }

// 正确模式：具体类型——编译时检查
#[wasm_bindgen]
pub fn process(input: &[u8]) -> Vec<u8> { ... }

JsValue 的问题不仅是类型安全——还有运行时开销。每个 JsValue 背后都是一个 JS 对象的引用：创建它要在 externref 表里占一格（§6.6），它被 drop 时（Rust 作用域结束自动发生，mem::forget 掉才会泄漏）要把这一格还回去，转换它要来回过一次胶水代码。而 u32、bool 这类数值类型走的是纯数值 ABI，压根不碰那张表（&[u8] 也不碰表，但要按 §20.3 说的复制一次）。按 §10.5 的实测，按值传一个 JsValue 约 37 ns，是 i32 调用（约 5 ns）的七倍多。

20.11 决策十一：测试策略

WASM 项目的测试策略与原生项目不同——WASM 编译和浏览器启动的开销使得"所有测试都在 WASM 环境中运行"不现实。第 18 章的可观测性方案为测试提供了基础设施。

测试金字塔

graph TD
  A["10% 浏览器集成测试<br/>wasm-pack test --chrome<br/>验证 JS 互操作、DOM 交互"] --> B["20% WASM 功能测试<br/>wasm-pack test --node<br/>验证编译正确、绑定正确"]
  B --> C["70% 纯 Rust 测试<br/>cargo test<br/>验证核心逻辑、边界条件"]
  C --- D["执行快（无 WASM 编译）<br/>可用标准 Rust 测试工具<br/>覆盖所有核心逻辑"]
  B --- E["验证 WASM 编译通过<br/>验证 wasm-bindgen 绑定正确<br/>需要 wasm-pack"]
  A --- F["验证真实浏览器环境<br/>验证 JS 侧行为<br/>速度最慢"]
  style C fill:#10b981,color:#333
  style B fill:#f59e0b,color:#333
  style A fill:#dc2626,color:#fff

代码组织

测试策略的核心原则是核心逻辑与 WASM 绑定分离——核心逻辑可以在 cargo test 中直接测试，不需要 WASM 编译：

// 核心逻辑——不依赖 WASM，可以在 cargo test 中直接测试
pub fn core_grayscale(data: &mut [u8]) {
    for pixel in data.chunks_exact_mut(4) {
        let gray = (pixel[0] as f32 * 0.299
                  + pixel[1] as f32 * 0.587
                  + pixel[2] as f32 * 0.114) as u8;
        pixel[0] = gray;
        pixel[1] = gray;
        pixel[2] = gray;
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test] // 70% 层：纯 Rust 测试，cargo test 直接运行
    fn test_grayscale() {
        let mut data = [255, 128, 64, 255];
        core_grayscale(&mut data);
        let expected = (255.0 * 0.299 + 128.0 * 0.587 + 64.0 * 0.114) as u8;
        assert_eq!(data[0], expected);
        assert_eq!(data[3], 255); // alpha 不变
    }
}

// WASM 绑定层——只在 WASM 功能测试中验证
#[wasm_bindgen]
pub fn grayscale(data: &mut [u8]) {
    core_grayscale(data) // 委托给核心逻辑
}

推荐：70% 纯 Rust 测试 + 20% WASM 功能测试 + 10% 浏览器集成测试（经验比例）。纯 Rust 测试不需要 WASM 编译、不需要拉起浏览器——反馈快得多，能进 pre-commit 而不只是 CI。核心逻辑必须与 WASM 绑定分离——这是可测试性的基础，也是第 20.6 节"构建目标选择"中条件编译组织的直接动力。

20.12 决策十二：版本策略

.wasm 二进制的兼容性比 JS 更严格——JS 可以做 polyfill，WASM 不能。一个函数签名变更在 JS 中可能只是"新增参数带默认值"（向后兼容），在 WASM 中则是破坏性变更（WASM 函数没有默认参数；导入函数的签名对不上时，实例化直接以 LinkError 失败）。

版本策略的三个维度

维度一：SemVer 严格遵循。公共 API 的任何破坏性变更必须升 major 版本。WASM 的"公共 API"包括所有 #[wasm_bindgen] 导出的函数签名、导出的内存布局、WIT 接口定义。一个容易忽略的破坏性变更是"给枚举添加变体"。这在 Rust 里本来就算破坏性变更（下游的穷尽 match 会编译失败，除非枚举标了 #[non_exhaustive]），而跨到 JS 侧还要再坏一层：JS 没有穷尽性检查，switch 遇到新变体只会静默走 default 分支——编译不报错、运行时才错。如果这个枚举值还参与序列化，新旧版本的互操作就会直接失败。

维度二：双平台发布。wasm-pack publish 发布 npm，cargo publish 发布 crates.io——两者版本号必须保持一致：

# 发布流程
# 1. 更新 Cargo.toml 版本号
# 2. 运行测试
cargo test
wasm-pack test --node

# 3. 同时发布
cargo publish                          # crates.io
wasm-pack publish                      # npm

维度三：.wasm 二进制哈希。在 package.json 中记录 .wasm 文件的 SHA-256——CDN 缓存失效的依据，也是供应链完整性验证的手段。下面的 wasmHash 是发布脚本自己写进去的约定字段，wasm-pack 不会生成它：

// JS 侧验证 .wasm 文件完整性（--target web 产物）
import init from './pkg/my_wasm_lib.js';
import pkg from './pkg/package.json' with { type: 'json' };

async function loadWasm() {
  const response = await fetch('my_wasm_lib_bg.wasm');
  const buffer = await response.arrayBuffer();
  const hash = await crypto.subtle.digest('SHA-256', buffer);
  const hexHash = Array.from(new Uint8Array(hash))
    .map(b => b.toString(16).padStart(2, '0')).join('');

  const expectedHash = pkg.wasmHash['my_wasm_lib_bg.wasm']
    .replace('sha256-', '');

  if (hexHash !== expectedHash) {
    throw new Error('WASM binary hash mismatch — possible corruption or CDN issue');
  }

  // 0.2.118 的 init 要求传单个对象；直接传 buffer 会打印弃用警告
  return init({ module_or_path: buffer });
}

这种哈希验证不仅用于缓存失效——还用于检测 CDN 污染和供应链攻击。如果攻击者替换了 CDN 上的 .wasm 文件，哈希校验会失败并阻止加载。它和 SRI（Subresource Integrity）是同一个思路，可靠程度也一样：fetch() 本身就接受 integrity 选项（值写成 sha256-<base64>），哈希不符时请求直接失败；手写校验的好处只是能自定义报错与上报。两种做法都有同一个前提：期望的哈希值不能和 .wasm 来自同一个可能被污染的源。

20.13 反模式：什么时候不该用 WASM

前 12 条决策都假定"WASM 是合理选择"——但这个假定本身需要先验证。WASM 不是性能银弹，错误的场景下会让代码更慢、更复杂、更难维护。识别这些反模式比掌握模式更重要。

20.13.1 五个明确的反模式

graph TD
  A["反模式识别"] --> B["纯 DOM 操作"]
  A --> C["浏览器 API 密集调用"]
  A --> D["JSON/字符串处理"]
  A --> E["小模块大体积"]
  A --> F["跨边界高频调用"]
  B --> B1["WASM 必须经 web-sys 跨边界<br/>性能反而不如直接写 JS"]
  C --> C1["每次 API 调用都跨 JS-WASM 边界<br/>纯 JS 没有这个开销"]
  D --> D1["JSON.parse 是引擎内置的原生实现<br/>WASM 版还要加边界开销"]
  E --> E1["几十行计算也要十几 KB 的 WASM<br/>下载 + 编译开销 > 计算节省"]
  F --> F1["微调用密集场景<br/>单次纳秒级 × N 累计可观"]
  style A fill:#dc2626,color:#fff

反模式一：纯 DOM 操作。Yew/Leptos 用 WASM 写 UI 看似优雅——但每个 document.createElement 都要跨 JS-WASM 边界，每个事件监听都要 Closure::wrap 在 externref 表里占一格。这类应用的工作量几乎全是 DOM 调用，而 DOM 只能从 JS 侧调——WASM 在这里没有任何主场优势，只是多了一层"借道"。

反模式二：浏览器 API 密集调用。任何"调用几十次 localStorage.getItem + 解析 JSON + 处理结果 + 写回"的逻辑，WASM 版都可能比纯 JS 更慢。原因：每次 web_sys::window().local_storage() 都是一次跨边界调用，取回的字符串还要做一次 UTF-16 → UTF-8 的编解码——而纯 JS 这两笔开销都是零。

反模式三：JSON/字符串处理。JSON.parse 在 V8 里是 C++ 实现的内置函数，性能接近原生。serde_json 在 WASM 中要做同样的解析工作，还要额外付一次"把字符串搬进线性内存"的编码开销——起跑就落后。除非要做的不只是解析（例如解析 + 复杂校验 + 结构变换，且结果不用回传 JS），否则交给 JSON.parse 更划算。

反模式四：小模块的大体积代价。一个只有几十行 Rust 计算的项目，经 wasm-bindgen 出来的 .wasm 也是十几 KB 起步——本专栏实测一个只导出两个小函数（其一用了 format!）的 crate，opt-level = "z" + LTO + wasm-opt -Oz 之后 .wasm 约 14KB，另有约 7KB 的 JS 胶水（Rust 1.96.0、wasm-bindgen 0.2.118、Binaryen 126），其中默认分配器 dlmalloc 那一套就占了大头（第 9 章的最小 cdylib 为 11,834 字节）。传输 + 编译 + 实例化都要算进首次调用的账里；同样的逻辑用纯 JS 可能只有几百字节。只有当"WASM 省下的执行时间 × 调用次数 > 一次性的加载与编译开销"时，引入 WASM 才划算。注意右边是一次性的、左边是随调用次数累加的——所以判断的关键不是单次快多少，而是这段代码一个会话里要跑多少次。

反模式五：高频微调用。for (let i = 0; i < 1000000; i++) wasm.tick(i) 这种循环的总开销几乎全在跨边界——按 §10.5 实测的约 5 ns 估，一百万次调用光边界开销就是约 5 毫秒，tick 本身若只是几条算术指令，就被边界开销盖过了。把循环放进 WASM（wasm.tick_batch(0, 1000000)）是必须的——但这要求 API 从一开始就按批量化来设计，事后再改就是破坏性变更。

20.13.2 决策表：选 WASM 还是不选

场景	WASM 还是 JS	理由
图像滤镜（卷积、模糊、色彩调整）	WASM	计算密集 + 像素批处理 + SIMD 加速
视频编解码（已有 wasm 库如 ffmpeg.wasm）	WASM	WebCodecs 只管编解码本身，容器解析、滤镜和它不支持的编码格式仍要靠 wasm 库
加密/哈希（SHA256、AES）	WASM	位运算密集 + WebCrypto API 缺特定算法
WebSocket 消息分发	JS	纯 IO，无计算瓶颈
Form 验证	JS	简单逻辑，本来就不是瓶颈
Markdown 渲染	视情况	短文本：JS；长文档：先在目标设备上对比两版再定
PDF 解析	WASM	复杂二进制格式 + 现成 Rust 库（pdf-rs）
数据可视化（D3 替代品）	JS	DOM 操作密集，纯 JS 框架成熟度高
游戏渲染 + 物理	WASM	Bevy/Macroquad 生态成熟，计算密集
Markdown 编辑器（核心+预览）	混合	编辑用 JS（CodeMirror），预览渲染用 WASM

20.13.3 用基准数据驱动决策

避免反模式的最可靠方法：在引入 WASM 前做对比基准。同一个算法实现 JS 和 WASM 两版，在目标用户的真实设备上测量：

async function comparePerformance(input) {
    const sizes = [100, 1000, 10000, 100000];
    for (const n of sizes) {
        const data = generateInput(n);
        const tJs = await timing(() => jsImpl(data));
        const tWasm = await timing(() => wasmImpl(data));
        console.log(`n=${n}: JS=${tJs}ms, WASM=${tWasm}ms, ratio=${(tJs/tWasm).toFixed(2)}`);
    }
}

经验阈值：加速比不到两倍就别引入了——这点收益抵不过 WASM 带来的复杂度：团队学习成本、构建链路、新的运维环节、调试痛点。而且要在目标用户的真实设备上测，不是在开发机上测（见下一节的"坑 1"）。

20.14 渐进式迁移：从 JS 项目到 WASM

大多数生产项目不是从零开始的——而是已有几年的 JS 代码库，想把性能热点逐步迁移到 WASM。这种迁移有成熟的工程套路。

20.14.1 五阶段迁移路径

flowchart LR
  A["阶段 1<br/>识别热点"] --> B["阶段 2<br/>POC 验证"]
  B --> C["阶段 3<br/>双实现共存"]
  C --> D["阶段 4<br/>渐进切流"]
  D --> E["阶段 5<br/>下线 JS 实现"]
  style A fill:#6366f1,color:#fff
  style E fill:#10b981,color:#333

阶段 1：识别热点（1-2 周）。用生产环境的真实数据找出 P95 耗时最长的纯计算函数。纯计算很关键——意味着函数只接受参数返回结果，不调用 DOM/IO。这种函数迁移成本最低，收益最直接。

阶段 2：POC 验证（2-4 周）。把一个候选函数实现 Rust 版本，测对比性能。如果 WASM 版本加速 < 2x，重新评估——是否选错了热点（可能问题不在 CPU 而在 IO），或者算法本身没有 SIMD/并行机会。

阶段 3：双实现共存（持续）。把 WASM 实现和 JS 实现都集成到代码中，用一个开关控制：

const useWasm = featureFlag('use_wasm_image_filter', { rolloutPct: 0 });

export function applyFilter(image, filter) {
    if (useWasm && wasmModule) {
        return wasmModule.apply_filter(image, filter);
    }
    return jsApplyFilter(image, filter);
}

阶段 4：渐进切流（4-12 周）。从 1% 用户开始切流到 WASM 实现，监控错误率、性能指标、用户反馈。每周提升一档（1% → 5% → 25% → 50% → 100%）。监控的核心指标：

错误率：WASM 实现是否有边缘情况下的崩溃（特别是低端设备）
性能：P50/P95/P99 是否真的改善
资源：WASM 加载是否影响首屏
用户感知：核心业务指标（转化、停留）是否恶化

阶段 5：下线 JS 实现（2-4 周）。100% 切流稳定 4 周后，删除 JS 实现代码，移除 feature flag。这一阶段最常被跳过——结果代码中长期保留两份实现，维护成本翻倍。强制下线纪律。

20.14.2 迁移中的常见坑

坑 1：低端设备上的收益远小于开发机。开发机上测出来的加速比，在低端 Android 上往往要打个大折扣。原因不是"低端设备没有优化编译器"——V8 对 WASM 是双层的：Liftoff 是快速产出代码的基线编译器，TurboFan 是优化层（其 WASM 流水线的 IR 已换成 Turboshaft，§4.3），两者在所有设备上都在。差别在于升层需要时间和 CPU：低端设备核少、频率低、还可能因为发热降频，代码在基线版本上停留的时间比开发机长得多；同时 JS 那一侧的 JIT 也在同样受影响，两边一起变慢，比值就被压平了。如果目标用户里低端设备占比高，务必在真机上重测，不要拿 POC 的数字做决策。

坑 2：WASM 加载失败的 fallback。某些用户的浏览器（老 Safari、企业代理后的 Chrome）可能加载 .wasm 失败。代码必须有 fallback 到 JS 实现，否则这部分用户直接报错。

坑 3：边缘情况的输出不一致。JS 的数字一律是 f64，Rust 版本常改用 f32 或整数：精度不同，浮点转整数的取整规则也可能不同（§19.2 就撞上了 Uint8ClampedArray 就近取整与 as u8 截断的差别）；整数溢出在 Rust release 下回绕、debug 下 panic；NaN 的位模式 WASM 规范也允许不确定。迁移前需要写大量对比测试——同一组输入两份实现的输出必须一致，做不到 bit-identical 的地方要明确容差。

20.14.3 何时不应迁移

如果发现以下情况，停止迁移：

团队中没有 Rust 工程师 → 引入 Rust 的隐性成本巨大
项目活跃度低（年改动 < 10 次） → 投入产出不划算
已经有性能压力但不在 CPU 上（在网络/IO） → WASM 解决不了
WASM 加速 < 2x 且数据量小 → 加载开销吃掉收益

20.15 模块粒度：什么大小的 WASM 才合适

12 条决策没回答一个根本问题：一个 WASM 模块该多大、包含什么。这个粒度决策影响项目的可维护性、性能、团队协作，分量不亚于技术选型。

20.15.1 三种粒度模式

graph TD
  A["WASM 模块粒度"] --> B["单一巨型模块<br/>所有功能打包"]
  A --> C["多个小模块<br/>每功能一个"]
  A --> D["分层模块<br/>核心 + 按需扩展"]
  B --> B1["✓ 部署简单<br/>✗ 启动慢<br/>✗ 加载多余代码"]
  C --> C1["✓ 按需加载<br/>✗ 接缝多<br/>✗ 总体积可能更大"]
  D --> D1["✓ 平衡<br/>需要明确的核心边界"]
  style B fill:#dc2626,color:#fff
  style C fill:#f59e0b,color:#333
  style D fill:#10b981,color:#333

长期演进的大型项目常常收敛到模式 D：一个尽量小的核心模块必加载，其余按需加载。第 19.10 节的 VS Code Web 就是这种形态：每种语言的 grammar 是独立的 .wasm，按需加载——总量不小，但用户实际下载的是首屏加上当天用到的那几种语言。

20.15.2 模块大小的甜点区间

下表是经验区间，不是实测基准——加载时间强依赖网络与 CDN，编译时间强依赖设备和引擎是否走流式编译（instantiateStreaming 能让编译与下载重叠，把两段时间摊成一段）：

体积区间	加载感受	编译开销	适用
< 50 KB	基本无感	可忽略	工具函数、单一功能
50-500 KB	首屏可接受	尚可	中型应用核心
500KB-2MB	明显可感	开始显著	大型应用核心
2-10 MB	需要加载态 UI	显著	桌面级应用
> 10 MB	不可接受	主导首屏	必须分块

甜点区间大致在几百 KB——足够装下有意义的功能，又不至于拖垮首屏。超过 1MB 就该认真考虑代码分割，几 MB 以上强烈建议重新设计模块边界。另外别忘了这里说的都是压缩前的口径：.wasm 走 br/gzip 传输通常能压掉一多半，但编译时间是按解压后的字节数算的——压缩能救加载，救不了编译。

20.15.3 拆分模块的依据

flowchart TD
  A["何时拆分模块?"] --> B{"功能是否独立?"}
  B -->|是| C{"使用频率?"}
  B -->|否| D["不要拆<br/>耦合代码合并体积更小"]
  C -->|高频| E["合并到核心"]
  C -->|低频| F["拆分按需加载"]
  A --> G{"加载体积 > 500KB?"}
  G -->|是| H["强制拆分"]
  A --> I{"团队所有权独立?"}
  I -->|是| J["按团队拆分"]
  I -->|否| K["按功能拆分"]
  style D fill:#10b981,color:#333
  style F fill:#6366f1,color:#fff
  style H fill:#dc2626,color:#fff

不要为了"模块化"而过度拆分——每个跨模块边界都引入跨边界调用开销。一个 100KB 的合并模块可能比两个 60KB 的小模块更快——因为省了边界开销。

20.15.4 模块之间的边界设计

拆分的模块如何协作？三种模式：

模式	描述	适用
平行模块	模块各自独立，JS 主进程编排	互无依赖的功能
核心 + 插件	核心模块定义接口，插件模块实现	第三方扩展系统
流水线	输出作为下一模块的输入	数据处理流水线（如视频编辑）

每种模式的边界设计不同：

graph LR
  subgraph "平行模式"
    A1[Image WASM] --- A2[Audio WASM]
    A2 --- A3[Video WASM]
    A4[JS] -.编排.-> A1
    A4 -.编排.-> A2
    A4 -.编排.-> A3
  end
  subgraph "核心+插件"
    B1[Core WASM] --> B2[Plugin A WASM]
    B1 --> B3[Plugin B WASM]
  end
  subgraph "流水线"
    C1[Decoder] --> C2[Filter] --> C3[Encoder]
  end
  style A4 fill:#6366f1,color:#fff
  style B1 fill:#10b981,color:#333
  style C1 fill:#f59e0b,color:#333

20.15.5 边界设计的反模式

graph TD
  A["模块边界反模式"] --> B["1. 每个函数一个模块<br/>边界开销吃掉所有收益"]
  A --> C["2. 巨型核心模块<br/>1MB+ 必加载"]
  A --> D["3. 循环依赖<br/>A 依赖 B，B 依赖 A"]
  A --> E["4. 接口频繁变更<br/>跨团队协作崩溃"]
  A --> F["5. 共享状态跨模块<br/>违背模块独立性"]
  style A fill:#dc2626,color:#fff

每条都是真实踩过的坑。修复策略：

过度拆分：按"会不会一起被用到"重新归组，合并成有意义的功能模块
巨型核心：把核心拆分为"必加载 + 首屏后加载"两层
循环依赖：提取共同依赖到第三个模块
接口频繁变更：接口冻结期 + 严格 RFC 流程
共享状态：状态归属一个模块，其他模块通过 API 访问

20.15.6 粒度决策的 12 决策位置

模块粒度其实贯穿了 12 决策：

决策	与粒度的关系
决策一（架构定位）	决定核心模块的边界
决策二（互操作）	模块间通信的开销
决策七（体积 vs 性能）	拆分增加体积，合并增加加载时间
决策十（API 设计）	模块边界的 API 形态
决策十一（测试）	拆分越多测试越复杂
决策十二（版本）	每个模块独立版本号

模块粒度不是孤立决策——是这 12 条决策的综合输出。先做完上层决策（架构定位、互操作方案），再决定粒度才能保持一致性。

20.16 WASM 项目的失败模式与教训

成功案例（第 19 章）展示了 WASM 能做什么——但失败案例同样有价值。这一节整理 WASM 项目的常见失败模式，让读者避免同样的坑。

20.16.1 失败模式 1：性能优化幻想

症状：团队认为"用 WASM 重写性能会显著提升"，重写后却没改善甚至更糟。

根因：

业务瓶颈不在 CPU（在网络/IO）
WASM 边界开销吃掉了计算优化
选错算法

典型场景：把 JSON 解析重写为 Rust → WASM，结果反而比 JSON.parse 慢。原因见 §20.13 反模式三——浏览器的 JSON.parse 本来就是原生实现，WASM 版还要额外付一次字符串跨边界的编码开销。第 19.2 节的灰度实测也属此类：WASM 标量版比 V8 优化后的 JS 还慢。

教训：先 profile 找瓶颈，不要假设。

20.16.2 失败模式 2：体积失控

症状：上线后用户反馈页面加载慢——查看发现 .wasm 5MB+。

根因：

引入大量依赖（serde_json 完整版、chrono 等）
没做 wasm-opt
没考虑 brotli 压缩

典型场景：一个 markdown 渲染器的 WASM 模块在几个版本里膨胀了一两个数量级——每次都只是"顺手加了个 crate"，没有人在 PR 里看体积。

教训：CI 中加体积守门（§9.13）。

20.16.3 失败模式 3：调试黑盒

症状：生产事故难以定位——错误堆栈只显示 wasm-function[42]。

根因：

没启 console_error_panic_hook
名称段被丢掉（wasm-pack release 默认的 wasm-opt -O 不带 -g 就不输出名称段，§20.8）
没保留 DWARF，也没有对应的调试构建可复现

典型场景：生产中遇到偶发 trap，但因为名称段已被丢掉，堆栈里只剩 wasm-function[42]，只能靠反复加日志、猜测复现来定位。

教训：release 也保留必要的调试信息（§16.11）。

20.16.4 失败模式 4：维护成本爆炸

症状：项目运行 1 年后，团队发现"加新功能比改 bug 还慢"。

根因：

代码组织混乱（§6.18）
测试覆盖不足（§6.16）
文档缺失
关键工程师流失

典型场景：核心算法用 WASM 实现，而团队里只有一个人真正懂这条链路——这个人离开后模块变成没人敢动的黑盒，最终被重写回 JS。

教训：维护性是从一开始就要考虑的——特别是只有单一 owner 的 WASM 模块。§19.8 讨论的单人项目之所以能成立，靠的是维护者本人长期不间断的投入，这个前提在公司里几乎不可复制。

20.16.5 失败模式 5：团队能力错配

症状：项目立项时低估学习曲线——"我们都会 JS，加点 Rust 应该不难"。

根因：

Rust 学习曲线被低估
WASM 工程链复杂（§5.15 错误诊断手册涉及的全部）
没人有完整 WASM 经验

典型场景：一支纯 JS 背景的团队启动 WASM 项目，几个月过去仍卡在工具链和所有权模型上，交付物停留在 demo 级别。

教训：WASM 项目需要有资深 Rust 工程师作为种子。

20.16.6 失败模式 6：业务 ROI 不明

症状：技术团队开心地"完成了 WASM 重构"——但产品团队问"用户感觉到了吗？"

根因：

性能改善不在用户感知路径（如 JS 已经够快的场景）
引入复杂度但没解锁新功能
资源花在错的地方

典型场景：用 WASM 重写表单验证，把一个本来就在毫秒以内的操作再快一半——用户感知零变化，维护成本却上升了。

教训：技术决策必须有业务收益（§1.11 ROI 框架）。

20.16.7 失败模式 7：生态依赖过度

症状：跟随 WASM 生态的最新提案——半年后这些提案被废弃或重写。

根因：

用未稳定的提案
工具链碎片化
文档跟不上

典型场景：在某个 WASI 接口还处于提案阶段时就投入生产，接口定稿时语义已经变了，相关代码全部重写。

教训：生产用稳定提案，实验用 PoC。

20.16.8 失败模式 8：性能回归被忽视

症状：上线初性能好——半年后明显变慢。

根因：

没有持续性能监控
每次 PR 都加一点开销，累积起来巨大
没有性能预算

典型场景：热路径的耗时在一年里逐步上涨——没有任何一次 PR 是"大幅变慢"，但每个人都顺手加了一点跨边界调用、一次额外复制或一个"小依赖"。

教训：CI 加体积/性能守门（§9.13、§10.15）。

20.17 全专栏回顾

20 章的内容从规范到工具链到工程实践，拆解了 Rust + WebAssembly 全链路的每一个关键环节。

graph TD
  subgraph "开篇 + WASM 规范与虚拟机 (Ch 1-4)"
    A1["Ch1: 为什么需要 WASM"] --> A2["Ch2: WASM 规范"]
    A2 --> A3["Ch3: 线性内存模型"]
    A3 --> A4["Ch4: WASM 虚拟机"]
  end
  subgraph "Rust → WASM 工具链 (Ch 5-8)"
    B1["Ch5: wasm32 目标与代码生成"] --> B2["Ch6: wasm-bindgen"]
    B2 --> B3["Ch7: 类型映射"]
    B3 --> B4["Ch8: wasm-pack"]
  end
  subgraph "性能与优化 (Ch 9-11)"
    C1["Ch9: 体积优化"] --> C2["Ch10: 运行时性能"]
    C2 --> C3["Ch11: 内存通信"]
  end
  subgraph "超越浏览器 (Ch 12-15)"
    D1["Ch12: WASI 与 Preview 1"] --> D2["Ch13: WASI Preview 2"]
    D2 --> D3["Ch14: 组件模型"]
    D3 --> D4["Ch15: WIT 与 wit-bindgen"]
  end
  subgraph "工程实践 (Ch 16-20)"
    E1["Ch16: 浏览器集成"] --> E2["Ch17: 服务器端 WASM"]
    E2 --> E3["Ch18: wasm-tracing 与可观测性"]
    E3 --> E4["Ch19: 生产案例"]
    E4 --> E5["Ch20: 设计模式"]
  end
  A4 --> B1
  B4 --> C1
  C3 --> D1
  D4 --> E1
  style A1 fill:#6366f1,color:#fff
  style B1 fill:#22d3ee,color:#333
  style C1 fill:#f59e0b,color:#333
  style D1 fill:#10b981,color:#333
  style E1 fill:#dc2626,color:#fff

核心洞察

洞察一：WASM 是计算加速器，不是应用框架。这贯穿全专栏——从第 1 章的定位讨论，到第 16 章的浏览器集成模式，到第 19 章的生产案例验证。WASM 的价值不在于"替代 JS"，而在于"在 JS 不擅长的地方补位"——密集的、确定性的、可预测的计算。

洞察二：数据传递要算进总账，瓶颈在哪要靠测。第 11 章的分析和第 19.2 节的实测一致：wasm-bindgen 对切片参数的复制是固定开销，不随计算变快而变小（4K 图单向复制约 5ms），计算越快它占比越高；但在那个每字节只做几次乘加的灰度负载里，计算本身（约 44ms）才是大头，而且 WASM 标量版还比 V8 优化后的 JS（约 35ms）慢。设计 API 时让数据尽量常驻一侧、少跨边界，同时别默认"换成 WASM 就会更快"。

洞察三：能力安全是设计哲学，不是附加功能。WASM 的沙箱不是"限制"——而是"明确的授权"。第 14 章的组件模型用 WIT 声明能力需求，第 17 章的插件系统用沙箱隔离不可信代码，第 19.3 节的密钥句柄让密钥不进 JS 堆（它缩小的是意外泄漏面，挡不住已拿到页面执行权的 XSS）。能力安全让系统更安全——不是通过"封堵漏洞"，而是通过"减少攻击面"。

洞察四：组件模型是未来，wasm-bindgen 是当下。第 14-15 章展示的组件模型是 WASM 的演进方向——语言无关的互操作、标准化的接口定义、可组合的组件。但组件模型在浏览器端的工具链还不成熟——wasm-bindgen 仍然是浏览器场景的最优选择。两者不是对立的——wasm-bindgen 解决当下的工程需求，组件模型定义未来的架构方向。

12 条决策速查表

#	决策	推荐选项	关键权衡
1	WASM 定位	计算引擎	最小侵入 vs 代码复用
2	互操作方案	浏览器: wasm-bindgen, 服务器: 组件模型	成熟度 vs 标准化
3	内存分配	高频: 预分配, 一次性: 按需	性能 vs 代码复杂度
4	错误处理	Result + JsValue	可观测性 vs 体积
5	线程并发	默认单线程	简单性 vs 多核利用
6	构建目标	按部署环境选择	浏览器 vs WASI
7	体积 vs 速度	默认 opt-level=z, 热点 crate 单独用 3	加载时间 vs 计算速度
8	构建配置	三 profile 策略	开发效率 vs 发布质量
9	依赖管理	每个依赖审查体积影响	功能 vs 体积
10	API 设计	最少跨边界调用, 句柄非数据	性能 vs 便利性
11	测试策略	70/20/10 金字塔	速度 vs 覆盖面
12	版本策略	SemVer 严格 + 双发布 + 哈希验证	兼容性 vs 灵活性

这 12 条决策不是孤立的——它们相互影响。例如，选择"计算引擎"定位（决策一）自然导致 wasm-bindgen 互操作方案（决策二）和句柄式 API 设计（决策十）；选择"预分配"内存策略（决策三）需要 Processor 结构体，这又影响版本策略（决策十二）——Processor 的私有字段变更对 JS 侧不可见，但导出方法的签名变更需要升版本。

WASM 工程的核心方法论：先定位，再选方案，然后做权衡。没有"最佳实践"——只有"在特定约束下的合理选择"。