Wails 快速上手：用 Go + React 构建跨平台桌面应用

本文介绍 Wails 框架的快速上手流程，从环境准备到项目初始化、开发调试再到最终打包，帮助开发者用 Go + 前端技术栈快速构建跨平台桌面应用。

什么是 Wails

Wails 是一个开源的 Go 桌面应用开发框架，让你可以用 Go 作为后端逻辑，结合 React、Vue、Svelte 等现代前端框架构建桌面应用。它类似于 Electron，但使用系统原生 WebView 而非内嵌 Chromium，打包体积更小、内存占用更低。

环境准备

前置要求

安装 Wails 前需要确认以下工具已就绪：

bash

go version   # Go 1.18+
node -v      # Node.js 16+
npm -v       # 或 pnpm/yarn

安装 Wails CLI

当前稳定版为 Wails v2，安装命令：

bash

go install github.com/wailsapp/wails/v2/cmd/wails@latest

验证安装：

bash

wails version

检查系统依赖完整性：

bash

wails doctor

wails doctor 会自动检测平台依赖是否满足：

macOS：Xcode Command Line Tools
Windows：WebView2
Linux：WebKit/GTK 相关库

初始化项目

官方支持的所有模板

bash

wails init -n myapp -t react          # React (JavaScript)
wails init -n myapp -t react-ts       # React (TypeScript)
wails init -n myapp -t vue            # Vue (JavaScript)
wails init -n myapp -t vue-ts         # Vue (TypeScript)
wails init -n myapp -t svelte         # Svelte (JavaScript)
wails init -n myapp -t svelte-ts      # Svelte (TypeScript)
wails init -n myapp -t vanilla        # Vanilla (JavaScript)
wails init -n myapp -t vanilla-ts     # Vanilla (TypeScript)

查看所有可用模板：

bash

wails init -l

常用初始化参数

参数	说明	示例
`-n`	项目名称	`-n my-app`
`-t`	模板类型	`-t react-ts`
`-d`	指定输出目录	`-d ./desktop-app`
`-g`	初始化 Git 仓库	`-g`
`-ide`	生成 IDE 配置	`-ide vscode`

完整示例：

bash

# 创建项目到指定目录，带 Git 初始化和 VS Code 配置
wails init -n my-app -d ./projects -t react-ts -g -ide vscode

项目结构

text

my-wails-app/
├── build/          # 图标、打包资源
├── frontend/       # 前端代码 (React/Vue/Svelte)
├── app.go          # Go 后端逻辑，暴露方法给前端调用
├── main.go         # 桌面应用入口
├── go.mod          # Go 模块定义
├── go.sum          # Go 依赖锁定
└── wails.json      # Wails 项目配置

关键文件说明：

app.go：定义后端结构体和方法，通过 wails:generate 暴露给前端
main.go：应用入口，配置窗口参数（标题、尺寸、是否可调整等）
wails.json：项目元信息，包含名称、前端构建命令等配置
frontend/：标准前端项目，可使用任何前端工具链

Go 与前端通信

Wails 通过绑定机制实现 Go 和前端的双向通信。

Go 端定义方法

type App struct {
    ctx context.Context
}

func (a *App) Greet(name string) string {
    return fmt.Sprintf("Hello %s!", name)
}

前端调用

typescript

import { Greet } from '../wailsjs/go/main/App'

Greet("Wails").then(result => {
    console.log(result) // "Hello Wails!"
})

前端调用 Go 的事件系统

typescript

import { EventsOn, EventsEmit } from '../wailsjs/runtime/runtime'

// 监听 Go 端事件
EventsOn("file-loaded", (data) => {
    console.log("文件加载完成:", data)
})

// 向 Go 端发送事件
EventsEmit("user-action", { type: "click" })

开发与调试

开发模式

bash

wails dev

开发模式特性：

前端热更新（修改立即生效）
Go 端修改自动重编译
浏览器 DevTools 可用（右键检查元素）
支持在 Go 代码中使用 runtime.LogDebug 等日志方法

构建发布

bash

wails build

生成的桌面程序位于 build/bin/ 目录。

常用构建参数：

bash

# 生产构建（压缩）
wails build -ldflags "-s -w"

# 指定平台
wails build -platform windows/amd64
wails build -platform darwin/universal

# 带 UPX 压缩
wails build -upx

最小完整流程

从零开始，复制执行以下命令即可：

bash

# 1. 安装 CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# 2. 检查环境
wails doctor

# 3. 创建项目
wails init -n my-wails-app -t react-ts

# 4. 启动开发
cd my-wails-app && wails dev

# 5. 构建发布
wails build

Wails vs Electron 对比

特性	Wails	Electron
后端语言	Go	Node.js
渲染引擎	系统原生 WebView	内嵌 Chromium
打包体积	~10MB	~100MB+
内存占用	较低	较高
原生 API	通过 Go 调用	通过 Node.js
跨平台	Windows/macOS/Linux	Windows/macOS/Linux

Wails 的核心优势在于打包体积小、启动快、内存占用低，适合对性能和体积敏感的桌面应用场景。

项目链接

GitHub 仓库：https://github.com/wailsapp/wails
官方文档：https://wails.io/docs/introduction
模板市场：https://wails.io/docs/community/templates

字节笔记本

Wails 快速上手：用 Go + React 构建跨平台桌面应用

什么是 Wails

环境准备

前置要求

安装 Wails CLI

初始化项目

推荐模板

官方支持的所有模板

常用初始化参数

项目结构

Go 与前端通信

Go 端定义方法

前端调用

前端调用 Go 的事件系统

开发与调试

开发模式

构建发布

最小完整流程

Wails vs Electron 对比

项目链接