Vugu 示例程序构建与运行完全指南:mage 自动化与手工编译双路线

原创2026-10-14 13:16:431,709 阅读
文章标签:前端Web框架

Vugu 示例程序构建与运行完全指南:mage 自动化与手工编译双路线

导读

Vugu 是一个基于 Go + WebAssembly 的实验性 UI 库,仓库 examples 目录 内收录了从 simple、vg-if、vg-for 到 compound-component、html-form 等十余个可直接运行的示例模块。本文围绕 examples/Readme.md 这一核心构建文档,系统讲解 Vugu 示例的两条构建与运行路线:一条是使用 mage 与 Docker 的"一键式"自动化路线,另一条是脱离 mage、完全手写命令的通用路线。读完本文,你将掌握如何克隆仓库、用 mage Examples / mage SingleExample 批量或单个构建示例、通过本地 nginx 容器在浏览器中加载 .wasm,也能在无 mage 环境下手工完成 vugugen 代码生成、WebAssembly 交叉编译与静态服务部署。

构建前准备:克隆仓库与依赖检查

唯一获取途径:git clone

Vugu 的示例只能通过克隆整个仓库获得,它们不是独立的可发布模块,无法通过 go get 单独安装。文档明确指出这是获取示例的唯一方式:

git clone https://github.com/vugu/vugu
cd vugu

克隆完成后,所有示例位于仓库根目录下的 examples 目录。该目录下的每个子目录都是一个独立的 Go module(各自拥有自己的 go.mod),例如 examples/vg-if/go.mod 中声明了 module github.com/vugu/vugu/examples/vg-if,并依赖 github.com/vugu/vugu v0.4.0。这一点从 mage 源码中也可以印证:magefiles/modulehandler.go 的 modulesUnderDir 会遍历 examples 目录下所有子目录,通过 go list -m 逐个探测 module 名与源码目录,再将重复项去重后逐一构建。

拿到示例后,你可以选择原地构建,也可以把某个示例目录复制到别处再构建。

环境依赖

两条路线都需要以下前置工具:

  • Go 工具链:用于安装 vugu 包、vugugen 代码生成器,以及执行 WebAssembly 交叉编译;
  • Docker:mage 路线与手工路线都需要用 Docker 启动 nginx 容器来托管 .wasm 文件与 index.html;
  • mage:仅 mage 路线必需,可理解为 Vugu 项目自定义的"构建脚本解释器"。

主仓库 README.md 补充说明:mage 需要在 vugu 模块根目录(顶层 go.mod 所在目录)执行;mage 构建过程中还会调用 goimports(若未安装,magefiles/magefile.go 的 InstallGoImports target 会自动执行 go install golang.org/x/tools/cmd/goimports@latest 安装最新版)。

路线一:mage 自动化构建(推荐)

mage 是 Vugu 官方偏好的构建工具,它将"安装工具链 → 生成代码 → 交叉编译 → 启动 nginx 容器 → 清理环境"这一整套复杂流程封装成一个个 target,开发者只需记忆两条命令。

批量构建全部示例:mage Examples

在克隆后的 vugu 仓库根目录执行:

mage Examples

该命令会一次性构建 examples 目录下的所有示例。查看 magefiles/magefile.go 的 Examples target 实现可知,其完整流程为:

  1. 依次执行 Build(安装 vugu、vugugen、vugu cmd 与 vugufmt)与 PullLatestNginxImage(拉取 nginx:latest 镜像);
  2. 调用 StartLocalNginxForExamples() 启动本地 nginx 容器;
  3. 遍历 examples 下每个 module,逐个调用 buildModule 构建 WebAssembly 二进制。

构建单个示例:mage SingleExample

如果只想运行某一个示例,使用:

mage SingleExample <示例的 Go module 名>

例如构建 vg-if 示例:

mage SingleExample github.com/vugu/vugu/examples/vg-if

注意参数是模块名(module name)而非目录名。从 magefiles/magefile.go 的 SingleExample 实现看,它会先在 examples 下通过 modulesUnderDir 枚举所有模块,再按模块名精确匹配,找不到时返回 Could not find a module named %q 错误。该命令会构建目标示例以及全部 vugu 工具,保证示例始终使用最新版本的生成器工具构建。

启动成功的输出信息与访问方式

无论批量还是单个构建,成功后 shell 中都会输出:

Local nginx container started.
Connect to http://localhost:8889/<example-test-directory-name>
e,g. http://localhost:8889/fetch-and-display
To stop the local nginx container please run:
    mage StopLocalNginxForExamples

即访问地址格式为:

http://localhost:8889/<示例目录名>

例如查看 vg-if 示例,浏览 http://localhost:8889/vg-if/](http://localhost:8889/vg-if/)。该提示信息来自 [magefiles/magefile.go 的 StartLocalNginxForExamples target,端口 8889 在 magefiles/consts.go 中定义为 VuguNginxExamplesContainerPort。

修改示例后如何重新构建

修改了示例代码(如 root.go、root.vugu)后,需要重新执行:

mage Examples
# 或
mage SingleExample github.com/vugu/vugu/examples/vg-if

然后回到 http://localhost:8889/vg-if/](http://localhost:8889/vg-if/),刷新浏览器以重新加载新的 WebAssembly 文件。以 vg-if 示例为例,[examples/vg-if/Readme.md 演示了在 Root.ListLength() 中加一行 fmt.Printf 日志,重建并刷新后即可在浏览器 JavaScript 控制台看到列表长度输出。

停止与清理

运行完毕后,停止本地 nginx 容器:

mage StopLocalNginxForExamples

该 target 位于 magefiles/magefile.go,其底层通过 magefiles/dockercmd.go 的 stopContainerForExamples 对名为 vugu-nginx-examples 的容器执行 docker stop 与 docker rm(即使容器未在运行也会安全忽略错误)。

与 mage 全流程的关联

mage Examples 还常常作为 Vugu 完整 CI 流程的一环出现:例如 magefiles/magefile.go 的 All target 按顺序执行 Build → Lint → Test → TestVuguInit → TestWasm → Examples → StopLocalNginxForExamples,可见示例构建被纳入项目的整体质量门禁。

路线二:不使用 mage 的手工构建

说明:以下步骤是对 mage 内部行为的总结性复刻;若存在任何疑问,以 mage 实际执行的最顶层 magefiles/magefile.go 为准。

当你的环境无法使用 mage,或希望彻底理解构建原理时,可以手工完成同样五步:

第 1 步:安装 vugu 与 vugugen

# 安装 vugu 本身——后续步骤依赖 vugu 包
go install github.com/vugu/vugu

# 安装 vugugen 代码生成工具
go install github.com/vugu/vugu/cmd/vugugen

vugugen 是 Vugu 的 .vugu → .go 代码生成器,其入口 cmd/vugugen/vugugen.go 支持 -skip-go-mod、-skip-main、-tinygo、-s(单文件合并)与 -r(递归)等 flag,不传参数时默认处理当前目录。手工路线中 go install github.com/vugu/vugu 对应 mage 的 Build target 中的 goInstall("github.com/vugu/vugu")(见 magefiles/magefile.go)。

第 2 步:进入示例目录并生成 *_gen.go

# 从 vugu 克隆根目录进入目标示例,这里以 vg-if 为例
cd examples/vg-if

# 运行 vugugen,由 *.vugu 文件生成 *_gen.go 文件
vugugen

以 vg-if 为例,目录中的 root.vugu(模板文件)会被生成出 root_gen.go(Go 代码)。在 mage 流程中,这一步对应 magefiles/modulehandler.go 的 runVugugenInModuleDir——它会在模块目录内执行 vugu gen。值得注意的是:目前 mage 调用的是新一代 vugu 命令的 gen 子命令(cmd/vugu/vugu.go),而旧版独立的 vugugen 二进制仍然可用,二者生成逻辑同源于 gen 包。

此外,mage 还会在生成后执行 go mod tidy(modulehandler.go)以及从 GOROOT 复制与当前 Go 编译器版本匹配的 wasm_exec.js 到示例目录(modulehandler.go)——这是因为 Go 官方并未在 wasm_exec.js 内嵌入版本号,文件必须与编译器严格对应。

第 3 步:交叉编译 WebAssembly 二进制

# 现在已拥有全部 *.go 文件,可以构建 WebAssembly 了。
# 构建结果会在当前目录生成 main.wasm。
# 注意:go build 传入的是模块名,而不是源文件列表。
GOOS=js GOARCH=wasm go build -o ./main.wasm github.com/vugu/vugu/examples/vg-if

该命令与 mage 内部实现完全一致——magefiles/modulehandler.go 的 runGoBuildInModuleDir 正是设置 GOOS=js、GOARCH=wasm 环境变量后执行 go build -o ./main.wasm <module.name>。main.wasm 即浏览器最终加载的 WebAssembly 二进制。

第 4 步:用 nginx 容器托管静态文件

有了 .wasm 二进制后,还需要一个 Web 服务器来托管它以及配套的 index.html、其他 HTML 与样式表。Vugu 项目使用容器化的 nginx 完成这一工作。vg-if 示例对应的手工命令为:

# vugu-examples 是容器名
# 我们把整个 examples 目录 bind mount 进容器,
# 因此该容器可托管 examples 目录下任何一个已按前述步骤构建过的示例
# 8889 是对外暴露的访问端口
docker run --name vugu-examples --mount type=bind,source=./examples,target=/usr/share/nginx/html,readonly -p 8889:80 -d nginx

这条命令与 mage 的底层实现(magefiles/dockercmd.go 的 startNginxContainer)结构一致,mage 版本只是额外指定了固定容器名 vugu-nginx-examples,并把 wasm-test-suite/nginx-test.conf 作为自定义配置挂载进容器(target=/usr/share/nginx/config/config.d/nginx-test.conf)。

第 5 步:浏览器访问

打开浏览器访问:

http://localhost:8889/vg-if/

即可运行 vg-if 示例。其 index.html 展示了浏览器侧加载机制:页面引入 wasm_exec.js,然后在 WebAssembly.instantiateStreaming(fetch("/vg-if/main.wasm"), go.importObject) 中拉取并实例化 main.wasm,挂载点由 #vugu_mount_point 指定——这与 main_wasm.go 中 domrender.New("#vugu_mount_point") 的挂载点必须一致。

扩展:自定义 nginx 配置与其他 Web 服务器

如果需要向 nginx 容器提供不同的 nginx 配置,可以通过额外的 mount 参数完成。仓库中已有现成范例:wasm-test-suite/nginx-test.conf 为 test-012-router 配置了 URL 重写规则:

location /test-012-router/page[0..9]+ {
    rewrite /test-012-router/page[0..9]+ ^/test-012-router/index.html$ break;
}

如果你选用 nginx 之外的 Web 服务器,整体流程是类似的——本质上就是把 .wasm 文件与 index.html 通过任意静态文件服务器托管出去,浏览器端的加载逻辑不变。

手工路线的完整命令速查

以下是从零开始手工构建 vg-if 示例的完整命令序列,可直接复制执行:

# 1. 安装 vugu 与 vugugen(在仓库克隆目录外的任意位置亦可,二者是全局工具)
go install github.com/vugu/vugu
go install github.com/vugu/vugu/cmd/vugugen

# 2. 进入示例目录并生成代码
cd examples/vg-if
vugugen

# 3. 交叉编译 WebAssembly
GOOS=js GOARCH=wasm go build -o ./main.wasm github.com/vugu/vugu/examples/vg-if

# 4. 回到仓库根目录,启动 nginx 容器托管 examples 目录
cd ..
docker run --name vugu-examples --mount type=bind,source=./examples,target=/usr/share/nginx/html,readonly -p 8889:80 -d nginx

# 5. 浏览器访问
# http://localhost:8889/vg-if/

两条路线对比与适用场景

对比维度 mage 路线 手工路线
前置依赖 Go、Docker、mage Go、Docker
构建范围 支持批量(Examples)与单个(SingleExample) 一次一个示例
工具链版本 每次构建前自动重装最新 vugu 工具,保证一致性 需手动安装,工具可能滞后
代码生成 自动执行 vugu gen、go mod tidy、复制 wasm_exec.js 需手动执行 vugugen 等步骤
适用场景 开发调试、CI 流程、多示例演示 无 mage 环境、理解底层原理、定制构建

需要留意的是:mage 的构建细节(例如 modulehandler.go 中"先 vugu gen、再 go mod tidy、然后复制 wasm_exec.js、最后 go build"的顺序)是理解手工路线的权威依据,手工复刻时若遇到行为差异,应回头核对 magefile 源码。

延伸阅读

登录后查看全文
vugu