企业官网建设流程全解析

• 开发工具
• 系统底层

wazero 是一款完全用 Go 编写的 WebAssembly 运行时，以"零依赖"（zero dependency）为核心设计目标，让 Go 开发者能够在自己的应用中安全地执行由其他语言编译出的 Wasm 二进制。本文基于 wazero 官方站点首页内容，结合仓库源码与示例，带你完成 CLI 安装、Go 嵌入、基础调用与关键配置的完整实操，并理解其"零依赖"背后的设计原理。

什么是 wazero？

WebAssembly（简称 Wasm）是一种安全运行由其他语言编译而来的代码的方式。运行时（Runtime）负责执行 WebAssembly 模块（Module），这些模块最常见的形式是以.wasm为扩展名的二进制文件，同时也有对应的文本格式.wat可以阅读（仓库中大量测试数据同时提供两种格式，例如 fac.wat 与 fac.wasm）。

wazero是唯一一个完全用 Go 编写、没有任何外部依赖的 WebAssembly 运行时。所谓"零依赖"，指的是它在编译和运行过程中不依赖 CGO、不依赖共享库（shared libraries）或 libc 等系统前置条件，因此你可以保留 Go 的交叉编译能力（cross compilation），并且给最终二进制增加的体积非常小。

快速开始：两种使用方式

wazero 提供两种主流的使用形态：一种是开箱即用的命令行工具，另一种是以 Go 库的形式嵌入到你的应用里。

方式一：使用 wazero CLI 运行任何 Wasm 二进制

wazero 提供独立的 CLI 程序（源码位于 cmd/wazero/wazero.go），可以用官方安装脚本快速获取：

curl https://wazero.io/install.sh | sh ./bin/wazero run app.wasm

安装脚本默认把可执行文件安装到./bin目录（可以通过-b参数或环境变量BINDIR指定其他目录），并会从发布版本下载对应的平台二进制、校验 SHA-256 校验和后再解压安装，支持的平台包括 darwin/amd64、darwin/arm64、linux/amd64、linux/arm64（可参考仓库中的 site/static/install.sh）。安装后即可用wazero run直接运行任何.wasm模块。

方式二：在 Go 项目中嵌入 wazero

将 wazero 作为 Go 库嵌入，可以在任何应用里扩展出 WebAssembly 能力。获取最新版本：

go get github.com/tetratelabs/wazero@latest

嵌入的最小代码骨架如下（源自站点首页示例，对应的完整工程见 examples/basic/add.go）：

import "github.com/tetratelabs/wazero" // ... r := wazero.NewRuntime(ctx) defer r.Close(ctx) mod, _ := r.Instantiate(ctx, wasmAdd) res, _ := mod.ExportedFunction("add").Call(ctx, 1, 2)

这段代码做了四件事：

1. wazero.NewRuntime(ctx)创建一个运行时实例；
2. defer r.Close(ctx)确保关闭运行时及其创建的所有模块；
3. r.Instantiate(ctx, wasmAdd)从 Wasm 二进制实例化一个模块；
4. mod.ExportedFunction("add").Call(ctx, 1, 2)调用模块导出的add函数并拿到结果。

实战示例：用 Wasm 扩展 Go 应用

官方认为学习 wazero 最好的方式是动手跑一遍示例工程，其中最基础的 basic 示例 演示了如何用一个定义在 WebAssembly 中的加法函数扩展 Go 应用。仓库中该示例的宿主代码位于 examples/basic/add.go，运行方式为：

$ go run add.go 7 9 7 + 9 = 16

对应测试 examples/basic/add_test.go 断言了7 + 9 = 16这一输出，可以作为可复现的验证依据。

一步一解：完整宿主代码

以 examples/basic/add.go 为例，完整流程如下：

package main import ( "context" _ "embed" "errors" "flag" "fmt" "log" "strconv" "github.com/tetratelabs/wazero" "github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1" ) //go:embed testdata/add.wasm var addWasm []byte func main() { flag.Parse() ctx := context.Background() r := wazero.NewRuntime(ctx) defer r.Close(ctx) // 关闭本运行时创建的一切 // TinyGo 的 wasip1 目标需要 WASI 宿主函数（例如实现 panic） wasi_snapshot_preview1.MustInstantiate(ctx, r) mod, err := r.InstantiateWithConfig(ctx, addWasm, wazero.NewModuleConfig().WithStartFunctions("_initialize")) if err != nil { log.Panicf("failed to instantiate module: %v", err) } x, y, err := readTwoArgs(flag.Arg(0), flag.Arg(1)) if err != nil { log.Panicf("failed to read arguments: %v", err) } add := mod.ExportedFunction("add") results, err := add.Call(ctx, x, y) if err != nil { log.Panicf("failed to call add: %v", err) } fmt.Printf("%d + %d = %d\n", x, y, results[0]) }

需要注意几个关键点：

• go:embed嵌入 Wasm 二进制：addWasm通过//go:embed testdata/add.wasm在编译期直接嵌入宿主程序，无需运行时读取文件；
• WASI 导入：由于add.wasm使用 TinyGo 的wasi目标编译，需要先实例化 WASI 宿主模块，wasi_snapshot_preview1.MustInstantiate(ctx, r)一次性完成该工作（WASI 相关实现位于 imports/wasi_snapshot_preview1）；
• Start 函数：NewModuleConfig().WithStartFunctions("_initialize")用于配置实例化后要执行的启动函数，TinyGo 生成的模块需要先执行_initialize；
• 返回值：add.Call(ctx, x, y)返回一个uint64切片results，实际结果取results[0]。

编译 Wasm 二进制：guest 侧

示例中的 examples/basic/testdata/add.go 是 guest 侧源码，通过//go:wasmexport add导出加法函数：

//go:wasmexport add func add(x, y uint32) uint32 { return x + y } // main 是 `wasi` 目标所必需的，即使它没有被使用。 func main() {}

使用 TinyGo 编译得到.wasm（这也是把 Go 源码编译为 Wasm 最常见的方式）：

(cd testdata; tinygo build -buildmode=c-shared -target=wasip1 -o add.wasm add.go)

除了 TinyGo，AssemblyScript、C、C++、Rust、Zig 等许多语言都能编译到 Wasm 目标（仓库中 examples/allocation 演示了 Rust / TinyGo / Zig 三种语言的字符串传递方案）。这里顺带厘清两个概念：嵌入 wazero 的应用通常被称为host（宿主），被执行的 Wasm 二进制被称为guest（来宾）；guest 有时需要 imports（导入）来实现控制台输出等功能，TinyGo 的wasi目标就依赖 WASI 导入。

为什么"零依赖"？

"零依赖"是 wazero 区别于其他运行时最核心的卖点，其价值体现在三个层面：

1. 无 CGO、无系统前置条件：通过完全避开 CGO，wazero 不需要共享库、libc 等前置组件，安装和部署都更简单；
2. 保留交叉编译能力：纯 Go 实现意味着你可以像编译普通 Go 程序一样轻松为不同平台交叉编译；
3. 体积小：纯 Go 实现只为你的二进制增加很小的体积。

与此同时，wazero 的 API 提供了 Go 开发者所期望的特性，包括安全的并发（safe concurrency）和上下文传播（context propagation）。从源码结构看，runtime.go 中定义的核心接口Runtime也印证了这一点：Instantiate、InstantiateWithConfig、CompileModule、InstantiateModule等方法均以context.Context作为首个参数，从而让取消、超时等标准 Go 语义贯穿整个执行过程；而CloseWithExitCode配合原子变量记录关闭状态（见 runtime.go 的实现），保证了并发环境下的生命周期安全。

引擎选择：解释器还是编译器

运行时内部支持多种执行引擎。从 runtime.go 的实现可以看出，NewRuntimeWithConfig会根据RuntimeConfig自动选择合适的引擎：当平台支持且特性允许时优先使用 wazevo 编译器引擎（位于 internal/engine/wazevo），否则回退到解释器引擎（位于 internal/engine/interpreter）。对于大多数用户而言，wazero.NewRuntime(ctx)的默认配置已经足够，无需关心引擎细节。

什么时候可以使用 wazero？

wazero 早已进入可用状态：其1.0 版本发布于 2023 年 3 月，并且已被众多开源项目和线上生产环境使用。仓库维护了一份不完全的使用者清单 site/content/community/users.md，涵盖图像编解码库（如 go-pdfium、AVIF/HEIC/JPEG XL 相关库）、通用插件体系（如 Extism、go-plugin、waPC）、中间件（如 http-wasm-host-go）、网络基础设施（如 dapr、mosn、Redpanda Connect）以及 Kubernetes 场景的 Wasm 部署工具等。

获取最新版本依旧很简单：

go get github.com/tetratelabs/wazero@latest

进阶：运行时与模块的关键配置

为了让嵌入更贴合生产需求，wazero 提供了两层配置对象：RuntimeConfig（运行时级）与ModuleConfig（模块级）。

RuntimeConfig：控制运行时行为

RuntimeConfig位于 config.go，所有WithXXX方法都遵循不可变（immutable）模式——每次调用都返回包含变更的新实例。常用配置项包括：

ModuleConfig：控制模块实例化

模块级配置用于每次实例化，常见用法包括：

• WithName(name)：为模块实例命名，便于之后用r.Module(name)取回；
• WithStartFunctions("_initialize")：指定实例化后依次执行的启动函数（如前面 TinyGo 示例所示）；
• 标准输入输出、环境变量、参数（argv）等 sys 相关配置，用于为 guest 提供宿主侧的能力。

如果你只是按默认方式实例化一次，直接使用r.Instantiate(ctx, wasm)即可；当同一个二进制需要多次实例化（例如以不同名字创建多份）时，推荐先用r.CompileModule编译一次，再反复r.InstantiateModule，避免重复解码与编译——这是 runtime.go 中Runtime接口注释明确建议的模式。

WASI：让 guest 拥有系统能力

WASI（WebAssembly System Interface）为 Wasm 模块提供文件、时钟、随机数、进程等系统级能力。wazero 在 imports/wasi_snapshot_preview1 下实现了完整的 WASI preview1 宿主模块（包括 args、clock、environ、fs、poll、proc、random、sched、sock 等子模块），通过wasi_snapshot_preview1.MustInstantiate(ctx, r)一行即可注入运行时。配合 fsconfig.go 提供的WithFSMount等文件系统配置，可以让 guest 安全地读写宿主文件系统的指定目录。

总结

wazero 为 Go 开发者提供了一个简单、安全、零外部依赖的 WebAssembly 运行方案：CLI 适合快速验证与脚本化运行，Go 库适合深度嵌入。掌握NewRuntime/Instantiate/ExportedFunction().Call这条核心链路后，再配合RuntimeConfig与ModuleConfig按需调优内存、特性与启动行为，即可在自己的项目中稳定地运行由任意语言编译的 Wasm 模块。想继续深入，可以从 examples 的多个实战工程（字符串传递、多返回值、并发实例化、跨运行时共享编译缓存等）开始，并结合 site/content/specs.md 了解 wazero 对 WebAssembly 规范的覆盖情况。

• 开发工具
• 系统底层