Vugu 示例程序构建与运行完全指南:mage 自动化与手工编译双路线
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 实现可知,其完整流程为:
- 依次执行
Build(安装vugu、vugugen、vugucmd 与vugufmt)与PullLatestNginxImage(拉取nginx:latest镜像); - 调用
StartLocalNginxForExamples()启动本地 nginx 容器; - 遍历
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 步:浏览器访问
打开浏览器访问:
即可运行 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 源码。
延伸阅读
- examples 目录:全部示例源码,每个子目录即一个独立 Go module
- examples/vg-if/Readme.md:单个示例的构建、运行与修改说明
- magefiles/magefile.go:mage 全部 target 的定义(
Examples、SingleExample、StartLocalNginxForExamples等) - magefiles/modulehandler.go:模块发现、构建与测试的底层实现
- magefiles/dockercmd.go:nginx / chromedp 容器的具体启动参数
- cmd/vugugen/vugugen.go:
vugugen命令行工具入口 - README.md:主仓库中关于示例运行与新建示例(复制
fetch-and-display并修改go.mod、index.html两处路径)的补充说明