Wails v2 Vue-TS 模板完全指南：用 Vue 3 + TypeScript + Vite 构建跨平台桌面应用

Wails v2 Vue-TS 模板完全指南用 Vue 3 TypeScript Vite 构建跨平台桌面应用【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails本指南围绕 Wails v2 官方模板vue-ts展开讲解如何基于 Vue 3、TypeScript 与 Vite 搭建桌面应用前端并通过wails dev获得毫秒级热更新与浏览器调试能力、通过wails build产出可分发的生产包。读完本文你将掌握该模板的目录结构、前后端绑定机制、wails.json配置要点以及从零到发布的全流程操作。模板概览官方 Vue-TS 模板能做什么模板位于仓库的 v2/pkg/templates/templates/vue-ts 目录是 Wails v2 官方提供的 Vue Vite TypeScript 前端脚手架。其元信息定义在 template.json 中{ name: Vue Vite (Typescript), shortname: vue-ts, author: Lea Anthony, description: Vue Vite development server, helpurl: https://wails.io }它解决的问题非常明确开发者只需要熟悉 Vue 生态即可用 Wails 创建原生桌面应用——Go 负责系统级能力与业务逻辑Vue 3 负责界面渲染二者通过 Wails 的绑定层进行类型安全的方法调用。模板开箱即用无需手工拼接 Vite 配置、Go 嵌入资源或前后端通信管道。模板目录结构与职责划分用wails init -n myapp -t vue-ts或wails3 init系列的等价命令创建项目后你得到的核心结构如下├── app.go # App 结构体与 Greet 方法后端业务逻辑 ├── main.go # 程序入口配置窗口与资源服务 ├── wails.json # 项目配置前后端命令与构建参数 ├── go.mod # Go 模块定义 └── frontend/ # Vue 3 TypeScript Vite 前端 ├── package.json ├── tsconfig.json ├── tsconfig.node.json ├── vite.config.ts ├── index.tmpl.html ├── wailsjs/ # 自动生成的 Go ↔ JS 绑定代码勿手改 └── src/ ├── main.ts ├── App.vue ├── style.css ├── vite-env.d.ts ├── assets/ # 字体与 logo 资源 └── components/ └── HelloWorld.vue后端模板中的 app.tmpl.go 定义了App结构体、NewApp()构造器与startup生命周期回调并提供了一个返回字符串的Greet(name string) string示例方法——这是前后端交互的最小可运行范例。前端frontend/src下是标准的 Vue 3 工程入口 main.ts 通过createApp(App).mount(#app)挂载根组件。自动生成目录frontend/wailsjs由 Wails 在构建时自动生成例如 wailsjs/go/main/App.js 中的Greet函数实际调用window[go][main][App]Greet同时提供配套的 App.d.ts 类型声明让 TypeScript 获得完整的类型提示。配置解析wails.json 是项目的控制中枢模板的配置模板位于 wails.tmpl.json初始化时会根据项目名、作者等信息渲染成实际的wails.json{ $schema: https://wails.io/schemas/config.v2.json, name: {{.ProjectName}}, outputfilename: {{.BinaryName}}, frontend:install: npm install, frontend:build: npm run build, frontend:dev:watcher: npm run dev, frontend:dev:serverUrl: auto, author: { name: {{.AuthorName}}, email: {{.AuthorEmail}} } }各字段的作用如下字段模板默认值说明name{{.ProjectName}}项目名称渲染为你在wails init时指定的名字outputfilename{{.BinaryName}}生成的可执行文件名二进制名frontend:installnpm install首次构建前安装前端依赖的命令frontend:buildnpm run build生产模式下构建前端产物vue-tsc --noEmit vite buildfrontend:dev:watchernpm run dev开发模式下启动 Vite 热更新服务器的命令frontend:dev:serverUrlauto开发服务器地址auto表示 Wails 自动探测 Vite 的端口author.name/author.email渲染自作者信息生成原生应用包元数据时使用frontend:dev:serverUrl的auto模式会自动从 Vite 的stdout中识别实际监听地址因此你几乎不需要手工指定端口——这与模板 frontend/vite.config.ts 中默认端口配置Vite 未显式设置时取 5173配合即可无缝工作。后端入口main.go 如何把 Vue 前端嵌入桌面窗口模板的 main.go.tmpl 渲染后形成应用入口核心代码如下//go:embed all:frontend/dist var assets embed.FS func main() { app : NewApp() err : wails.Run(options.App{ Title: {{.ProjectName}}, Width: 1024, Height: 768, AssetServer: assetserver.Options{ Assets: assets, }, BackgroundColour: options.RGBA{R: 27, G: 38, B: 54, A: 1}, OnStartup: app.startup, Bind: []interface{}{ app, }, }) ... }关键点//go:embed all:frontend/dist生产构建时frontend:build会把 Vue 应用编译到frontend/dist该目录随后被 Go 的embed打包进可执行文件。这意味着最终产物是自包含的单一二进制不需要外部 Web 服务器或安装 Node 环境。AssetServer通过assetserver.Options提供嵌入式静态资源服务将 Vue 构建产物作为应用资源加载。Bind把App结构体实例绑定到前端运行时Greet方法因此暴露给 JS 侧调用。OnStartup在窗口初始化完成后回调app.startup将context.Context保存到结构体中供后续调用 Wails 运行时 API如事件、对话框、窗口控制等使用。Greet方法定义在 app.tmpl.go// Greet returns a greeting for the given name func (a *App) Greet(name string) string { return fmt.Sprintf(Hello %s, Its show time!, name) }这是理解绑定机制的最小案例任何导出首字母大写方法都会被 Wails 反射扫描并生成对应的 JS 封装。前端调用 GoHelloWorld.vue 里的绑定实战模板的示例界面在 HelloWorld.vuescript langts setup import {reactive} from vue import {Greet} from ../../wailsjs/go/main/App const data reactive({ name: , resultText: Please enter your name below , }) function greet() { Greet(data.name).then(result { data.resultText result }) } /script template main div idresult classresult{{ data.resultText }}/div div idinput classinput-box input idname v-modeldata.name autocompleteoff classinput typetext/ button classbtn clickgreetGreet/button /div /main /template值得注意的实践模式导入路径指向自动生成的绑定import {Greet} from ../../wailsjs/go/main/App。生成的 App.js 内部调用window[go][main][App]Greet配合 App.d.ts 提供参数与返回值的类型声明。异步调用约定Go 方法在 JS 侧返回 Promise用.then()或async/await消费结果。包名与模块名对应go/main/App中的main是 Go 包名模板默认package mainApp是结构体名如果你自定义了结构体或包名重新运行wails dev/wails build会重新生成对应路径的绑定代码。如果新增了 Go 方法例如func (a *App) GetVersion() string只要重新启动wails devWails 就会自动重新生成绑定文件前端即可像调用Greet一样调用新方法全程类型安全。开发模式wails dev 与浏览器调试模板 README 描述的两种开发体验是提升效率的核心1. 窗口内热更新在项目根目录执行wails dev该命令会启动 Vite 开发服务器来自frontend:dev:watcher的npm run dev启动一个本地 WebSocket 桥接把 Vue 代码变更以毫秒级速度热更新到正在运行的桌面窗口中前端依赖未安装时自动执行frontend:installnpm install。由于 Vue 3 Vite 的 HMR模块热替换能力你在frontend/src中的每次保存都会即时反映到窗口界面无需重启 Go 进程Go 代码改动则需重启。2. 浏览器调试模式模板 README 明确说明还有一个开发服务器运行在 http://localhost:34115。在浏览器中连接该地址你可以像调试纯 Web 应用一样使用 DevTools同时仍能访问全部 Go 绑定方法——也就是说你可以在浏览器控制台直接调用Greet(wails)这类绑定函数排查前端问题不必依赖桌面窗口。该端口的默认值在源码中有据可查Wails 项目配置的DevServer字段默认绑定localhost:34115见 v2/internal/project/project.go模板初始化后生成的 NEXTSTEPS 说明文档见 v2/cmd/wails/internal/template/base/NEXTSTEPS.md.template同样会提示你访问该地址验证应用运行状态。生产构建wails build 与自包含产物当开发完成在项目根目录执行wails build该命令依次完成运行frontend:build即npm run build模板中为vue-tsc --noEmit vite build——先用vue-tsc做全量类型检查再让 Vite 产出优化后的frontend/dist静态资源将frontend/dist通过//go:embed嵌入 Go 二进制编译 Go 代码产出以outputfilename命名的可执行文件按目标平台生成可分发的安装包/应用包Windows 下为.exemacOS 下为.appLinux 下为可执行文件。最终交付物无需用户安装 Node.js、Vite 或任何前端运行时——前端资源已全部打包进原生二进制这保证了应用分发的低门槛与跨平台一致性。进阶建议新增页面与路由可在frontend/src下按 Vue 惯例组织组件与路由引入vue-router并把HelloWorld.vue替换为你的真实业务组件。扩展 Go 方法在App结构体上新增导出方法即可自动暴露给前端涉及耗时任务时建议使用 Wails 运行时的事件机制做异步进度反馈。调整窗口行为main.go中的Width、Height、BackgroundColour等选项可按需修改更多窗口、菜单、托盘等能力可查阅options包的源码v2/pkg/options。管理 wailsjs 生成物frontend/wailsjs属于生成文件不要手工编辑若绑定方法更新后前端没有及时获得新类型重启wails dev即可强制重新生成。参考资源模板元信息v2/pkg/templates/templates/vue-ts/template.json项目配置模板v2/pkg/templates/templates/vue-ts/wails.tmpl.json后端入口模板v2/pkg/templates/templates/vue-ts/main.go.tmpl后端示例方法v2/pkg/templates/templates/vue-ts/app.tmpl.go前端依赖与脚本v2/pkg/templates/templates/vue-ts/frontend/package.json前端入口组件v2/pkg/templates/templates/vue-ts/frontend/src/components/HelloWorld.vue自动生成绑定示例v2/pkg/templates/templates/vue-ts/frontend/wailsjs/go/main/App.js开发服务器默认端口定义v2/internal/project/project.go【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考