环境搭建与Wails3初体验
01 - 环境搭建与 Wails3 初体验
本章目标
- 安装 Go 1.25+ 和 Node.js 18+
- 安装 Wails3 CLI
- 理解 Wails3 项目结构
- 跑通第一个 Wails3 桌面窗口
- 了解开发模式的热重载机制
1.1 安装 Go
Windows
去 go.dev/dl 下载 .msi 安装包，双击安装即可。
安装完成后打开终端验证：
go version
# go version go1.25.0 windows/amd64
macOS
brew install go
Linux
# 下载最新版本
wget https://go.dev/dl/go1.25.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz
# 添加到 PATH (写入 ~/.bashrc 或 ~/.zshrc)
export PATH=$PATH:/usr/local/go/bin
配置 Go 代理（国内推荐）
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOPRIVATE=git.mycompany.com
💡 知识点：
GOPROXY是 Go 模块代理，goproxy.cn是国内镜像，下载依赖更快。GOPRIVATE排除私有仓库不走代理。
1.2 安装 Node.js
Windows / macOS
去 nodejs.org 下载 LTS 版本（18.x 或 20.x），安装后验证：
node --version
# v20.11.0
npm --version
# 10.2.4
⚠️ 注意： Wails3 需要 Node.js 18+，不支持更旧的版本。
1.3 安装 Wails3 CLI
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
验证安装：
wails3 version
# wails3 v3.0.0-alpha.xx
📌 关键概念： Wails3 是 Wails 的第三代版本（v3），当前仍处于 alpha 阶段。它相比 v2 的主要变化是服务架构和绑定机制的彻底重构，更简洁、更 Go 化。
Windows 额外步骤
Wails3 在 Windows 上依赖 WebView2 Runtime：
- Windows 11：已内置，无需额外安装
- Windows 10：如果没装过，去 Microsoft Edge WebView2 下载 Evergreen Bootstrapper 安装
1.4 创建项目
# 创建项目目录
mkdir pet-content-creator
cd pet-content-creator
# 初始化 Go module
go mod init pet-content-creator
# 添加 Wails3 依赖
go get github.com/wailsapp/wails/v3@latest
1.5 写第一个 Wails3 应用
创建 main.go：
package main
import (
"embed"
"log"
"github.com/wailsapp/wails/v3/pkg/application"
)
//go:embed all:frontend/dist
var assets embed.FS
func main() {
// 创建 Wails 应用
app := application.New(application.Options{
Name: "pet-content-creator",
Description: "AI驱动的今日头条宠物内容创作工具",
Assets: application.AssetOptions{
Handler: application.AssetFileServerFS(assets),
},
Mac: application.MacOptions{
ApplicationShouldTerminateAfterLastWindowClosed: true,
},
})
// 创建主窗口
app.Window.NewWithOptions(application.WebviewWindowOptions{
Title: "今日头条宠物内容创作工具",
Width: 1200,
Height: 800,
URL: "/",
})
// 启动应用
err := app.Run()
if err != nil {
log.Fatal(err)
}
}
1.6 搭建前端
初始化 React + TypeScript + Vite
cd frontend
npm create vite@latest . -- --template react-ts
💡 注意：运行
npm create vite@latest .时，注意末尾的.表示在当前目录创建，不要创建嵌套目录。
安装依赖
npm install
修改 frontend/index.html
确保 index.html 有一个挂载点：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>宠物内容创作工具</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
修改 frontend/src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<App />
</React.StrictMode>
);
修改 frontend/src/App.tsx
function App() {
return (
<div style={{ padding: 40, fontFamily: "system-ui" }}>
<h1>🐾 今日头条宠物内容创作工具</h1>
<p>即将开始一段精彩的旅程...</p>
</div>
);
}
export default App;
1.7 第一次运行
开发模式（热重载）
# 在项目根目录运行
wails3 dev
此时 Wails3 会：
- 编译 Go 后端
- 启动 Vite 开发服务器（默认端口 9245）
- 打开桌面窗口，加载前端页面
你修改 Go 代码或前端代码，窗口都会自动刷新。
💡 知识点： Wails3 开发模式下，前端通过 Vite 的 HMR (Hot Module Replacement) 实现热更新；Go 后端修改后会重新编译并重启应用。这个过程通常在 2-3 秒内完成。
如果提示缺少 Taskfile
Wails3 v3 依赖 Taskfile 来管理构建任务。创建 Taskfile.yml：
version: '3'
vars:
APP_NAME: "pet-content-creator"
VITE_PORT: '{{.WAILS_VITE_PORT | default 9245}}'
tasks:
dev:
summary: Runs the application in development mode
cmds:
- wails3 dev -port {{.VITE_PORT}}
1.8 项目结构详解
运行 wails3 dev 几次后，项目目录会变成这样：
pet-content-creator/
├── main.go # 应用入口
├── go.mod # Go 模块定义
├── go.sum # Go 依赖校验
├── Taskfile.yml # 构建任务定义
│
├── backend/ # Go 后端代码
│ └── ... # (后续章节创建)
│
├── frontend/ # 前端代码
│ ├── index.html # 入口 HTML
│ ├── package.json # npm 依赖
│ ├── vite.config.ts # Vite 配置
│ ├── tsconfig.json # TypeScript 配置
│ ├── src/
│ │ ├── main.tsx # React 入口
│ │ ├── App.tsx # 主组件
│ │ └── App.css # 样式
│ └── bindings/ # Wails 自动生成的 TS 绑定
│ └── ... # (后续章节自动生成)
│
└── build/ # 构建产物
└── ...
关键文件说明
| 文件 | 作用 |
|---|---|
main.go |
应用入口，创建 Wails 实例、注册服务、创建窗口 |
go.mod |
Go 模块定义，管理后端依赖 |
Taskfile.yml |
构建任务编排（dev / build / package） |
frontend/package.json |
前端 npm 依赖声明 |
frontend/vite.config.ts |
Vite 构建配置 |
frontend/bindings/ |
Wails3 自动生成的前端绑定代码，从 Go struct 自动推导 TypeScript 类型 |
1.9 Wails3 的核心概念
Application
app := application.New(application.Options{...})
Application 是整个桌面应用的实例。它管理：
- 窗口（Window）— 可以创建多个
- 服务（Service）— 后端业务逻辑
- 菜单（Menu）— 系统菜单栏
- 资产（Assets）— 前端静态文件
Window
app.Window.NewWithOptions(application.WebviewWindowOptions{
Title: "我的应用",
Width: 1200,
Height: 800,
URL: "/", // 加载前端入口
})
Window 是一个 WebView 窗口，加载 / 路径下 embed.FS 中的前端文件。
Services
app := application.New(application.Options{
Services: []application.Service{
application.NewService(myService),
},
})
Service 是 Wails3 中最核心的概念之一。任何注册为 Service 的 Go struct，其公开方法会自动暴露给前端调用。这就是前后端的桥接机制。
📌 关键概念： Wails3 的 Service 模式替代了 v2 中的
Bind函数。你只需要注册一个 Go struct，前端就能直接调用它的方法，无需手写任何 IPC 代码。
1.10 Vite 配置
frontend/vite.config.ts 是 Vite 的配置文件：
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
});
这里只需要启用 React 插件即可。Wails3 在开发模式下会自动处理与 Go 后端的通信。
1.11 验证：修改代码看效果
实验 1：改窗口标题
在 main.go 中修改 Window 的 Title：
app.Window.NewWithOptions(application.WebviewWindowOptions{
Title: "🐾 我的第一个 Wails3 应用", // 改这里
Width: 1200,
Height: 800,
URL: "/",
})
保存后，Wails3 会自动重新编译 Go 代码并重启窗口，你会看到新标题。
实验 2：改前端文字
在 frontend/src/App.tsx 中修改：
<h1>🐾 今日头条宠物内容创作工具 v1.0</h1>
保存后，浏览器会通过 Vite HMR 立即更新，无需重启应用。
💡 知识点： 前端修改走 HMR（秒级热更新），Go 后端修改走重编译（3-5 秒重启）。这是 Wails3 开发体验的核心优势。
本章总结
| 你已经学会 | 对应能力 |
|---|---|
| 安装 Go + Node.js + Wails3 CLI | 开发环境就绪 |
main.go 写 Wails3 入口 |
创建桌面窗口 |
wails3 dev 启动开发模式 |
热重载开发 |
| Wails3 项目结构 | 知道每个文件的作用 |
| Application / Window / Service | 理解 Wails3 核心抽象 |
🔧 动手练习
- 将窗口尺寸改为 1024×768，观察变化
- 在
App.tsx中加一张本地图片，观察是否能显示 - 尝试添加第二个 Window（提示：再调用一次
app.Window.NewWithOptions） - 阅读
go.sum文件，看看有哪些间接依赖
