用 wazero CLI 运行 WebAssembly 命令行应用：examples/cli 示例全解析

• 开发工具
• 系统底层

本篇技术指南以 wazero 仓库中的 examples/cli 示例为骨架，讲解如何把一个用 Go 编写的命令行小工具编译成 WebAssembly 二进制，再通过 wazero CLI 直接执行，并让 Wasm 程序通过 WASI 读取宿主传入的命令行参数、向宿主标准输出写结果。读完本文，你将掌握wazero run的完整用法、参数传递的底层机制（WASIargs_get/args_sizes_get）、CLI 的常用选项，以及如何用测试代码验证 CLI 行为。

示例概览：一个"加法器" CLI 应用

examples/cli是一个麻雀虽小、五脏俱全的演示项目：一个简单的 CLI 应用程序被编译为 WebAssembly（cli.wasm），再由 wazero CLI 加载执行。原文档给出的最小运行命令是：

$ go run github.com/tetratelabs/wazero/cmd/wazero run testdata/cli.wasm 3 4

这条命令的语义是：在examples/cli目录下，用go run临时编译并启动 wazero CLI，run子命令加载testdata/cli.wasm，并把路径之后的3 4两个参数原样传递给 Wasm 程序。如果你在仓库根目录执行，等价写法为：

$ go run ./cmd/wazero run examples/cli/testdata/cli.wasm 3 4

执行结果会打印：

result: 7

wazero CLI 可以运行"独立（stand-alone）的 Wasm 二进制"：它不要求 Wasm 模块暴露任何特定的导出函数，也不要求调用方以库的方式嵌入 wazero；它更像一个轻量级的 Wasm 进程启动器。路径之后传入的所有参数都会被透传给 Wasm 程序，而 Wasm 程序则通过 WASI（WebAssembly System Interface）函数与宿主交互——本例中涉及读取参数（args_get等）与写标准输出（fd_write）。

读懂示例源码：cli.go 干了什么

示例的 Wasm 程序源码位于 examples/cli/testdata/cli.go，它是一段纯粹的、不依赖任何 wazero API 的标准 Go 程序，仅使用标准库的flag、os、strconv包：

package main import ( "flag" "os" "strconv" ) func main() { var sub bool flag.BoolVar(&sub, "sub", false, "whether to subtract arguments instead of add") flag.Parse() if flag.NArg() < 2 { os.Stdout.WriteString("bad arguments\n") os.Exit(1) } a, err := strconv.Atoi(flag.Arg(0)) if err != nil { os.Stdout.WriteString("bad arguments\n") os.Exit(1) } b, err := strconv.Atoi(flag.Arg(1)) if err != nil { os.Stdout.WriteString("bad arguments\n") os.Exit(1) } var res int if sub { res = a - b } else { res = a + b } os.Stdout.WriteString("result: " + strconv.Itoa(res) + "\n") }

程序逻辑非常直观，同时暗含了 Wasm CLI 编程的三个要点：

1. 参数解析：通过 Go 标准库flag包定义布尔开关-sub（默认false，表示执行加法；设为true则改为减法），然后flag.Parse()解析剩余参数。
2. 校验与错误处理：flag.NArg()检查参数个数是否至少为 2，strconv.Atoi负责把字符串转换为整数；任何失败都会向os.Stdout输出bad arguments并以退出码 1 结束（os.Exit(1)）。注意这里写的是标准输出而非标准错误，这是示例源码的实际行为，测试也正是按此断言。
3. 结果输出：计算完成后，把"result: " + 数值 + "\n"写入os.Stdout。

对应的预编译二进制 examples/cli/testdata/cli.wasm 已随仓库提供，可直接运行，无需自行构建。

用 wazero CLI 运行并传递参数

wazero CLI 的官方安装方式是 cmd/wazero/README.md 中记录的go install：

$ go install github.com/tetratelabs/wazero/cmd/wazero@latest

安装后，wazero run的用法约定是：第一个位置参数是 Wasm 二进制路径，其后所有内容都是传给 Wasm 程序的参数：

$ wazero run calc.wasm 1 + 2

原文中的命令行示例go run github.com/tetratelabs/wazero/cmd/wazero run testdata/cli.wasm 3 4与上面的形式完全等价——前者只是省去了"先安装、再调用"两步，适合在开发仓库内快速体验。

让我们用示例验证参数传递与-sub开关：

# 加法（默认行为） $ go run ./cmd/wazero run examples/cli/testdata/cli.wasm 3 1 result: 4 # 减法（传入 -sub=true） $ go run ./cmd/wazero run examples/cli/testdata/cli.wasm -sub=true 3 1 result: 2

这两条用例并非凭空设计，它们正是 examples/cli/cli_test.go 中TestRun的两个断言（"3","1"→result: 4；"-sub=true","3","1"→result: 2）。值得一提的是，Wasm 程序通过flag包把-sub=true识别为自己的开关参数，这说明 wazero CLI 不会吞掉任何用户参数——除了可选的--分隔符（见下文），路径之后的内容原样交给 Wasm。

参数传递链路在 CLI 实现中有明确落点：cmd/wazero/wazero.go的doRun中，wasmExe := filepath.Base(wasmPath)会把 Wasm 文件名作为argv[0]，随后：

conf := wazero.NewModuleConfig(). WithStdout(stdOut). WithStderr(stdErr). WithStdin(os.Stdin). WithRandSource(rand.Reader). WithFSConfig(fsConfig). WithSysNanosleep(). WithSysNanotime(). WithSysWalltime(). WithArgs(append([]string{wasmExe}, wasmArgs...)...)

也就是说，wazero CLI 默认把宿主的标准输出、标准错误、标准输入、随机源、文件系统配置、时钟与时间函数全部接通，并把argv[0]=cli.wasm与后续参数一起通过WithArgs注入模块配置——这正好对应示例中"可读参数、可写 stdout"的两个能力来源。CLI 文档（cmd/wazero/README.md）同样强调："除了参数，Wasm 二进制还可以访问 stdout、stderr 和 stdin。"

深入底层：CLI 如何"接通"WASI

示例文档指出，"The Wasm binary reads arguments and otherwise operates on the host via WASI functions"。要理解这句话，需要看 wazero CLI 的导入检测与 WASI 实例化逻辑（cmd/wazero/wazero.go）。

1. 按导入模块名自动选择模式

doRun编译模块后调用detectImports(guest.ImportedFunctions())，根据 Wasm 模块导入的函数所属模块名决定执行路径（wazero.go中的detectImports与importMode常量）：

• wasi_snapshot_preview1→modeWasi：调用wasi_snapshot_preview1.MustInstantiate(ctx, rt)实例化标准 WASI 宿主模块，再实例化用户模块。
• wasi_unstable→modeWasiUnstable：为旧版二进制兼容，把当前 WASI 函数以旧模块名wasi_unstable导出（见imports/wasi_snapshot_preview1/wasi.go中NewFunctionExporter的第二个使用场景注释）。
• 两者皆无→modeDefault：直接实例化，不挂载 WASI。

2. WASI 参数读取的实现

Wasm 侧调用 WASI 的args_sizes_get与args_get来获取参数。这两个宿主函数实现在 imports/wasi_snapshot_preview1/args.go：

• argsSizesGet：把参数个数（argc）与 NUL 结尾参数字节总长（argv_len）以小端序写入模块内存；
• argsGet：把每个参数的偏移量数组与 NUL 结尾的参数字符串本体分别写入内存。

两者都通过sysCtx.Args()拿到WithArgs注入的参数列表，这正是"wazero CLI 传递参数 → Wasm 程序用 flag 包解析"整条链路的事实基础。WASI 模块的整体导出清单（fd_write、args_get、proc_exit等约 40 个函数）可以在 imports/wasi_snapshot_preview1/wasi.go 的exportFunctions中看到。

3. 退出码与超时

模块实例化时会执行其_start入口（doRun注释明确说明："_start was called as part of instantiating the module"）。若程序调用proc_exit退出，wazero 返回*sys.ExitError，CLI 提取退出码并原样返回给宿主进程；若超时（-timeout）导致模块被强制关闭，则返回sys.ExitCodeDeadlineExceeded并打印超时错误。示例程序在参数非法时os.Exit(1)，最终宿主进程的退出码即为 1。

用测试锁定行为：cli_test.go 与 wazero_test.go

examples/cli/cli_test.go 通过//go:embed testdata/cli.wasm内嵌 Wasm 二进制，把文件写到临时目录后调用go run ../../cmd/wazero run <wasm路径> <参数>（若设置了WAZEROCLI环境变量则直接执行该 CLI 程序，便于跨架构容器环境跳过go run），再断言 stdout 内容：

CLI 自身更全面的测试在 cmd/wazero/wazero_test.go，其中TestRun覆盖了参数、--分隔符（wasmArgs以--开头时会被跳过，见doRun中if wasmArgs[0] == "--" { wasmArgs = wasmArgs[1:] }）、环境变量注入、只读挂载、-hostlogging各作用域日志、-cachedir、CPU/内存 profile、超时退出码以及wasi_unstable兼容模式等；TestRun_Errors则验证了各类错误路径（缺失文件、无效环境变量、非法挂载、负超时、非法监听地址等）均以退出码 1 结束并输出错误信息。

wazero CLI 完整选项参考

虽然示例只用到了最基础的run与参数透传，但 wazero CLI 为真实场景提供了丰富的选项，全部定义于 cmd/wazero/wazero.go。CLI 支持三个子命令：compile（预编译 Wasm 二进制）、run（运行 Wasm 二进制）、version（打印版本），全局-h打印用法。run子命令的选项如下：

compile子命令除-cachedir、-workers、-cpuprofile、-memprofile外，还提供-count <n>（重复编译次数，用于基准测试编译性能）。注意：-cpuprofile与-memprofile仅在仓库源码开发构建（version.GetWazeroVersion() == version.Default）时开放，go install的发布版默认不暴露这两个开关。

关于运行时选择的背景补充：wazero 提供编译器（默认，AOT 编译为原生码，速度通常比解释器高一个数量级）与解释器两种运行时，且整体零依赖、不需要 CGO——相关说明见仓库根 README.md。这也是 wazero CLI 能作为独立可执行文件分发的原因之一。

延伸阅读

• 本示例的入口文档：examples/cli/README.md
• 示例源码与预编译二进制：examples/cli/testdata/cli.go、examples/cli/testdata/cli.wasm
• CLI 测试：examples/cli/cli_test.go
• CLI 实现与完整选项：cmd/wazero/wazero.go、cmd/wazero/wazero_test.go、cmd/wazero/README.md
• WASI 参数读取实现：imports/wasi_snapshot_preview1/args.go；WASI 函数导出清单：imports/wasi_snapshot_preview1/wasi.go
• 更多 wazero 使用示例：examples/README.md（如 WASI I/O 示例位于 imports/wasi_snapshot_preview1/example）

• 开发工具
• 系统底层