wails-quickstart

name	wails-quickstart
description	Wails v3 安装、依赖检查、新建项目、第一个应用、项目结构解析。当用户问到「如何安装 wails3 / wails3 init / wails3 doctor / 项目目录结构 / 新手开始 / Go 版本要求 / WebView2 依赖」时使用。

Wails v3 - 快速开始

包含安装 Wails CLI、检查依赖、初始化项目、构建运行第一个应用、了解项目目录结构。

何时使用本 SKILL

• 第一次接触 Wails，需要安装环境
• 排查 wails3 doctor 报告的依赖缺失
• 用 wails3 init 新建项目
• 想了解 build/、frontend/、main.go、greetservice.go 等目录的职责
• 了解 Taskfile.yml / go.mod / package.json 的角色

关键摘要

系统要求

• Windows 10/11 AMD64/ARM64
• macOS 10.15+ AMD64（部署到 10.13+）/ macOS 11.0+ ARM64
• Ubuntu 24.04 AMD64/ARM64（其他 Linux 也可能可用）

必装依赖

依赖	要求	验证
Go	≥1.24（推荐 1.25）	go version
npm	模板需要（可选）	npm --version
Xcode CLT	macOS 必需	xcode-select --install
WebView2 Runtime	Windows 必需	wails3 doctor
gcc + gtk4 + webkitgtk-6.0	Linux 必需	wails3 doctor 会给出安装命令

Linux 旧栈：可用 -tags gtk3 切回 GTK3 + WebKit2GTK 4.1（v3.1 前保留）。

安装 CLI

正式版：

go install -v github.com/wailsapp/wails/v3/cmd/wails3@latest

开发版：

git clone https://github.com/wailsapp/wails.git
cd wails/v3/cmd/wails3
go install

⚠️ 开发版生成的项目用 Go replace 指向本地源码。

快速建项目

wails3 init -n myfirstapp
cd myfirstapp
wails3 build       # 生产构建
wails3 dev         # 开发模式（热重载）

或用 Task：

task dev      # = wails3 dev
task build    # 构建
task run      # 运行已构建的应用
task build:server   # 服务器模式（无 GUI）

标准项目结构（wails3 init 默认）

myfirstapp/
├── build/                    # 构建产物 + 平台资源
│   ├── appicon.png           # 应用图标
│   ├── config.yml            # 构建配置
│   ├── Taskfile.yml          # 顶层构建任务
│   ├── darwin/               # macOS（Info.plist、icons.icns）
│   ├── linux/                # AppImage / NFPM 打包
│   └── windows/              # NSIS、icon.ico、wails.exe.manifest
├── frontend/                 # 前端代码
│   ├── index.html
│   ├── main.js
│   ├── package.json
│   └── public/               # 静态资源
├── main.go                   # 应用入口
├── greetservice.go           # 示例服务
├── go.mod / go.sum
└── Taskfile.yml              # 项目根任务

绑定生成位置：frontend/bindings/<go-import-path>/<service>.{js,ts,d.ts}，构建/dev 时由 wails3 自动产出。

排查 wails3 not found

1. 确认 Go 安装正确，且 ~/go/bin 在 PATH 中
   • macOS/Linux：echo $PATH | grep go/bin
   • Windows：$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
2. 重启终端让新 PATH 生效

References 索引

主题	文件
完整安装文档（getting-started）	installation.md
你的第一个应用（含视频步骤）	your-first-app.md
安装替代版（quick-start）	quick-installation.md
项目结构详解	project-structure.md

链接到其他 SKILL

• 整体架构与原理 → wails-overview
• CLI 命令查询 → wails-cli
• 完整 todo/notes 教程 → wails-tutorials-migration
• 构建配置 / 跨平台 / 签名 → wails-build