news 2026/9/19 4:20:56

Wails Preact 官方模板深度指南：从 `wails dev` 热重载到 `wails build` 生产打包

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Wails Preact 官方模板深度指南：从 `wails dev` 热重载到 `wails build` 生产打包

Wails Preact 官方模板深度指南：从wails dev热重载到wails build生产打包

【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails

本篇技术指南以 Wails v2 官方 Preact 模板（v2/pkg/templates/templates/preact）为对象，完整解析该模板的项目结构、wails.json工程配置、Go 与 Preact 前端的双向绑定机制，以及wails dev实时开发与wails build生产构建的完整工作流。读完本文，你将能够基于该模板独立初始化一个 Preact + Vite + Wails 桌面应用，并理解其热重载、Go 方法调用与资产嵌入的底层原理。

模板概览与定位

Wails 的官方模板体系存放在 v2/pkg/templates/templates，每个模板由template.json（模板元信息）、wails.tmpl.json（工程配置模板）以及一组 Go/前端源码模板构成。Preact 模板是其中的官方模板之一，由template.json声明为：

{ "name": "Preact + Vite", "shortname": "preact", "author": "Lea Anthony", "description": "Preact + Vite development server", "helpurl": "https://wails.io" }

从描述可以看出，该模板的核心技术组合是Preact（前端 UI）+ Vite（开发服务器与构建工具）。Preact 作为 React 的轻量级替代品，提供了近似 JSX 的开发体验；Vite 则负责极速的模块热更新（HMR）与生产构建。两者与 Wails 的 Go 后端配合，构成了一个完整的桌面应用脚手架。

模板目录结构与角色分工

使用wails init选择该模板后，生成的项目会包含以下关键文件（以模板源文件*.tmpl.*对应生成产物）：

preact/ ├── main.go.tmpl # 生成 main.go，应用入口与 Wails 配置 ├── app.tmpl.go # 生成 app.go，业务结构体与 Greet 方法 ├── go.mod.tmpl # Go module 定义（含 Wails 依赖） ├── wails.tmpl.json # 生成 wails.json，工程级配置 ├── template.json # 模板元信息（供 wails init 读取） └── frontend/ ├── index.tmpl.html # 生成 index.html，前端入口 HTML ├── package.json # 前端依赖与 npm 脚本 ├── vite.config.js # Vite 配置（Preact 插件） ├── src/ │ ├── main.jsx # Preact 渲染入口 │ ├── app.jsx # 演示组件（调用 Go 的 Greet） │ ├── app.css / style.css └── wailsjs/ ├── go/main/App.js # 自动生成的 Go 绑定 └── runtime/ # Wails 运行时

关键点：frontend/dist是 Vite 构建的输出目录，main.go.tmpl通过//go:embed all:frontend/dist将其嵌入二进制，这也是最终可分发单文件应用的基础（详见下文“生产构建”一节）。

工程配置：wails.json 与模板变量

模板通过wails.tmpl.json生成工程根目录的wails.json。wails init在实例化时会用项目名、作者等信息替换其中的 Go 模板变量（{{.ProjectName}}、{{.BinaryName}}、{{.AuthorName}}、{{.AuthorEmail}}）：

{ "$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/outputfilename：应用名与最终二进制文件名。
  • frontend:install：wails命令在首次构建前自动执行的前端依赖安装命令，此处为npm install。
  • frontend:build：生产构建时执行的前端构建命令，即npm run build（内部调用vite build），产物输出到frontend/dist。
  • frontend:dev:watcher：开发模式下启动的前端监听命令，即npm run dev（内部调用vite）。
  • frontend:dev:serverUrl：设为auto时，Wails 会自动探测并连接 Vite 开发服务器地址，无需手动指定端口。

完整字段说明可参阅仓库中项目配置的解析实现 v2/internal/project/project.go，其中可以看到DevServer默认绑定地址为localhost:34115（见 project.go#L182）。

Go 侧源码模板：入口与绑定方法

main.go：应用窗口与资产服务器

main.go.tmpl生成了标准的 Wails v2 入口，要点如下：

//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, }, }) if err != nil { println("Error:", err.Error()) } }
  • //go:embed all:frontend/dist：将 Vite 构建产物嵌入 Go 二进制，AssetServer通过assetserver.Options提供这些静态资源，实现离线分发。
  • Bind：将App结构体暴露给前端 JS 调用。
  • OnStartup：应用启动时回调，用于保存context.Context供运行时 API 使用。
  • BackgroundColour：窗口背景色（深色 RGB(27, 38, 54)）。

app.go：默认 Greet 业务方法

app.tmpl.go提供了示例业务逻辑，这是前端调用 Go 代码的最小范例：

type App struct { ctx context.Context } func NewApp() *App { return &App{} } func (a *App) startup(ctx context.Context) { a.ctx = ctx } func (a *App) Greet(name string) string { return fmt.Sprintf("Hello %s, It's show time!", name) }

startup保存 context，便于后续调用 runtime 方法（如窗口控制、事件等）；Greet是默认的绑定方法，演示了 Go → JS 的参数传递与返回值。

go.mod：Wails 依赖模板

go.mod.tmpl声明 Go 模块与 Wails v2 依赖，其中{{.WailsVersion}}会在初始化时替换为实际版本号：

module changeme go 1.23.0 require github.com/wailsapp/wails/v2 {{.WailsVersion}} // replace github.com/wailsapp/wails/v2 {{.WailsVersion}} => {{.WailsDirectory}}

前端源码：Preact 组件与自动生成的 Go 绑定

入口与组件

index.tmpl.html定义页面骨架，包含#app挂载点并引入./src/main.jsx；main.jsx将App组件渲染到该节点。app.jsx是核心演示组件，展示了典型的Preact 状态 + Wails 绑定调用模式：

import {Greet} from "../wailsjs/go/main/App"; import {useState} from "preact/hooks"; export function App(props) { const [resultText, setResultText] = useState("Please enter your name below 👇"); const [name, setName] = useState(''); const updateName = (e) => setName(e.target.value); const updateResultText = (result) => setResultText(result); function greet() { Greet(name).then(updateResultText); } // ...渲染输入框、按钮与结果区域 }

注意Greet返回的是一个 Promise，这是 Wails 绑定生成的异步调用形态——前端通过window['go']['main']['App']['Greet']与 Go 后端通信，见 frontend/wailsjs/go/main/App.js：

export function Greet(arg1) { return window['go']['main']['App']'Greet'; }

wailsjs目录由 Wails 在构建/开发时自动生成，开发者不应手工编辑；类型定义App.d.ts与runtime.d.ts可提供编辑器智能提示。

Vite 与依赖

package.json声明了前端依赖与脚本：

{ "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" }, "dependencies": { "preact": "^10.24.0" }, "devDependencies": { "@preact/preset-vite": "^2.10.0", "vite": "^7.0.0" } }

vite.config.js仅需接入@preact/preset-vite插件即可获得 JSX 转换与 HMR 支持：

import {defineConfig} from 'vite' import preact from '@preact/preset-vite' export default defineConfig({ plugins: [preact()] })

实时开发：wails dev 与双服务器机制

在项目根目录运行wails dev即进入实时开发模式。其工作方式为：

  1. Wails 根据wails.json中的frontend:dev:watcher启动 Vite 开发服务器，对前端改动提供极速热重载（HMR），浏览器/窗口内的界面几乎实时刷新，无需重新编译 Go。
  2. Wails 自身的开发服务器默认运行在http://localhost:34115（该地址定义于 v2/internal/project/project.go#L182）。在浏览器中打开该地址，同样可以访问应用界面并调用 Go 方法——这意味着你可以在浏览器开发者工具（devtools）中直接调试前端与 Go 绑定，而不必每次都在原生窗口中操作。
  3. frontend:dev:serverUrl设为auto时，Wails 自动完成 Vite 服务器地址的发现与连接，无需手工配置端口。

生产构建：wails build

当开发完成，需要发布可分发的生产包时，运行：

wails build

该命令的执行链路是：

  1. 依据wails.json中的frontend:build执行npm run build，由 Vite 将 Preact 前端构建、压缩到frontend/dist。
  2. Go 编译器通过//go:embed all:frontend/dist把静态资源整体嵌入二进制。
  3. 依据outputfilename生成可执行文件，即无需外部 Web 服务器、可独立分发的桌面应用。

一个典型的发布流程因此是：wails dev迭代功能 →wails build产出安装包/二进制。开发与生产两条链路由wails.json中的frontend:*四组命令串接，这也是理解该模板（以及所有 Wails v2 官方模板）的关键。

小结

Wails 官方 Preact 模板是一条完整、可直接落地的“Go 后端 + Preact 前端”桌面开发链路：

  • 工程配置集中在wails.json，四组frontend:*命令统辖安装、构建与开发监听；
  • 开发体验由wails dev提供 Vite 热重载，并通过localhost:34115支持浏览器内联调试；
  • 前后端通信由自动生成的wailsjs绑定层完成，前端以 Promise 形式调用 Go 方法；
  • 发布能力由wails build+//go:embed实现单二进制分发。

参照上述源码与配置，你即可在此基础上替换app.go中的业务方法、扩展 Preact 组件，快速构建自己的 Wails 桌面应用。更完整的项目配置字段说明可继续阅读 Wails 官方项目配置文档，并结合仓库中的 模板生成逻辑 与 项目配置解析 深入理解。

【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/19 4:19:44

React并发渲染：useDeferredValue与useTransition的本质区别与场景选择

React 并发渲染的面试题里，useDeferredValue和useTransition这对兄弟出现的频率越来越高。很多朋友学完这两个 API 之后的第一反应是：这俩不都是让界面别那么卡的吗？到底有啥区别？我在实际项目里试过之后发现，它们背后…

作者头像 李华
网站建设 2026/9/19 4:16:58

机载LiDAR数据处理全流程：从POS解算到DEM生成的关键技术解析

简介：一份系统讲解机载激光雷达组成与数据处理流程的PPT课件，适合测绘、电力、林业、环境监测等领域的初学者、相关专业学生及教学培训使用。课件围绕LiDAR基本工作原理展开，不仅介绍了激光雷达设备、GPS/IMU定位定姿系统、数据记录系统等硬件…

作者头像 李华
网站建设 2026/9/19 4:15:12

纵横交叉算法优化神经网络结合小波变换的电力负荷预测方法

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/19 4:13:43

ResNet18+LSTM活体检测实战：基于OULU-NPU视频时序建模

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华