WASM 工具链与自定义段：wasm-tools、WAT 与二进制裁剪

cargo install wasm-tools      # 或 brew install wasm-tools
wasm-tools --help

validate   校验模块结构、类型与特性使用是否合法
print      反汇编为 WAT        parse      把 WAT 编译为二进制
dump       打印段结构（段 ID、偏移、大小），不解析指令
objdump    展示类型/函数/导入导出/内存等详细视图
strip      移除自定义段（name、producers、DWARF）
shrink     保守裁剪（保留语义，去掉冗余）
compose    链接多个模块         component  组件模型的 new/embed/wit
mutate     随机变异模块做 fuzz  smith      生成随机合法模块
metadata   读写 producers、dylink 等元数据段

wasm-tools validate module.wasm                 # 入口把关
wasm-tools dump module.wasm                     # 看段布局
wasm-tools print module.wasm | head -40         # 看真实指令

(module
  (memory (export "mem") 1 4)          ;; 初始 1 页，最大 4 页
  (func $fib (export "fib") (param $n i32) (result i32)
    (if (result i32) (i32.lt_s (local.get $n) (i32.const 2))
      (then (local.get $n))
      (else (i32.add
          (call $fib (i32.sub (local.get $n) (i32.const 1)))
          (call $fib (i32.sub (local.get $n) (i32.const 2)))))))
  (global $counter (mut i32) (i32.const 0))
)

wasm-tools parse fib.wat -o fib.wasm      # WAT → 二进制
wasm-tools print fib.wasm -o fib.wat      # 二进制 → WAT
wasm-tools print fib.wasm | wasm-tools parse -o roundtrip.wasm  # 往返一致性

Custom Section 布局：
  0x00            section id
  <u32 LEB128>    段总字节数
  <name>          段名字符串（长度前缀 + UTF-8）
  <bytes>         自定义负载（工具自由解释）

wasm-tools objdump module.wasm | grep -A3 custom
wasm-tools metadata show module.wasm          # 展示 producers 段
wasm-tools metadata add --name mytool module.wasm -o out.wasm

典型 producers 段内容：
  processed-by: emscripten 3.1.61
  processed-by: wasm-opt 116
  language: C++

wasm-opt -Oz input.wasm -o output.wasm            # 体积优先
wasm-opt -O3 input.wasm -o output.wasm            # 速度优先
wasm-opt --print-passes                            # 列出全部 pass
wasm-opt -Oz --inlining-optimizing --converge \
         --dce --remove-unused-names input.wasm -o out.wasm

常用 pass：
  dce                 死代码消除       inlining-optimizing  内联 + 后续优化
  remove-unused-names 去未引用名称     simplify-locals      局部变量简化
  precompute          常量预计算       memory-packing       合并相邻数据段
  vacuum              清理无用指令与段

实测（一个约 1.2MB 的 C++ 模块）：
  未优化               1204 KB
  -O2                  838 KB
  -Oz                  611 KB
  -Oz + strip name 段  576 KB
  -Oz + strip + brotli 168 KB（传输体积）

wat2wasm / wasm2wat   WAT ↔ 二进制（校验严格）
wasm-objdump          反汇编与段信息（类似 objdump）
wasm2c                把 WASM 转成 C 源码（移植到无 WASM 环境）
wasm-decompile        反编译为更易读的类 C 伪代码
wasm-interp / wasm-strip  简易解释器 / 移除自定义段

wasm2wat module.wasm -o module.wat          # 更接近原始结构的输出
wasm-objdump -x module.wasm                 # 详细段与符号表
wasm-decompile module.wasm -o module.dcmp   # 近似 C 的可读输出

选择建议：
  新项目 / 组件模型 / 复杂加工 → wasm-tools
  反汇编阅读 / wasm2c 移植      → WABT
  两者都能做的（wat↔wasm）      → 按团队习惯，别混用

拆分的三个动机：按需加载（首屏只加载核心模块）、复用（公共库独立成模块）、
增量更新（只更新变化模块，缓存命中率高）

wasm-ld --allow-undefined --export-all -o core.wasm core.o

# 方式一：wasm-tools compose（组件模型路线）
wasm-tools compose core.wasm -d deps/ -o composed.wasm

# 方式二：运行时动态链接（如 Wasmtime 的 linker）
wasmtime run --preload lib=lib.wasm app.wasm

// Wasmtime 侧手动链接两个模块
let mut linker = Linker::new(&engine);
linker.module(&mut store, "lib", &lib_module)?;   // 先实例化依赖
let instance = linker.instantiate(&mut store, &app_module)?;

wasm-tools strip module.wasm -o stripped.wasm          # 去掉全部自定义段
wasm-tools strip -d module.wasm -o no_dwarf.wasm       # 只去 DWARF，留 name 段
wasm-tools shrink module.wasm -o shrunk.wasm           # 保守裁剪

常见可裁剪项与收益（1.2MB 模块实测）：
  .debug_*（DWARF） -180 KB     name 段 -35 KB     producers 等 -2 KB
  未使用的导出函数 -20 ~ 60 KB  重复的数据段 -10 KB 级

# Brotli 对 wasm 压缩效果极好（二进制结构重复度高）
brotli -q 11 -o module.wasm.br module.wasm
# 服务器配置：Content-Encoding: br, Content-Type: application/wasm

实测压缩率（-Oz 产物）：gzip -9 约 32%，brotli -11 约 27%，zstd -19 约 30%

# 编译期生成 DWARF（Rust / C++）
rustc --target wasm32-unknown-unknown -g -C debuginfo=2 -O lib.rs
# 保留 name 段便于堆栈可读
wasm-opt --strip-debug --keep-section=name in.wasm -o out.wasm

DWARF（.debug_* 段）能映射到源码行，体积大，仅本地/内测保留
name 段只保留函数名，体积小，可长期保留
两者都去掉体积最小，但运行时堆栈全是 func[42] 这样的编号

# 让运行时能把 wasm 偏移映射回源文件
wasm-tools print app.wasm -o app.wat
# 或使用 emscripten/wasm-bindgen 生成的 .wasm.map + sourceMappingURL 段

// Wasmtime 侧开启符号化堆栈
let mut config = Config::new();
config.wasm_backtrace_details(WasmBacktraceDetails::Enable);

wasm-tools validate --features simd,threads module.wasm
wasm-tools validate --features all module.wasm          # 检查全部已支持特性
wasm-opt --enable-simd --enable-threads in.wasm -o out.wasm

特性支持矩阵（简化）：
  MVP / mutable-globals / sign-ext   所有或绝大多数运行时都支持
  simd                               主流运行时均支持
  threads                            需 SharedArrayBuffer 与运行时开关
  exceptions / gc / 尾调用            较新，支持面最窄，需显式开启

兼容性策略：用最低公共特性集编译；CI 用 wasm-tools validate --features 卡口；
需要新特性时先确认全部目标运行时都支持；记录每个产物的特性使用情况随版本发布

#!/usr/bin/env bash
set -euo pipefail
SRC=build/app.wasm; OUT=dist/app.wasm
wasm-tools validate --features simd,threads "$SRC"
wasm-opt -Oz --converge "$SRC" -o "$OUT"
wasm-tools strip -d "$OUT" -o "$OUT"          # 去 DWARF，留 name
wasm-tools metadata add --name ci-pipeline "$OUT" -o "$OUT"
wasm-tools validate "$OUT"
brotli -q 11 -f -o "$OUT.br" "$OUT"
echo "size: $(stat -c%s "$OUT") bytes, br: $(stat -c%s "$OUT.br") bytes"

[ ] 入口 validate 通过（含目标特性集）
[ ] -Oz 后体积纳入基线，超阈值告警
[ ] strip 掉 DWARF，保留 name 段
[ ] producers 段记录工具链版本
[ ] 压缩产物与原始产物同时发布
[ ] 体积变化写入 CI 报告，做版本间对比
[ ] 第三方模块必须验证签名与 producers 来源