wails

我能做什么

• 设置并验证 Wails 所需环境（Go、Node/NPM、平台依赖项）
• 使用 wails init 创建项目，并选择模板/框架
• 通过 wails dev 运行开发工作流，并说明实时重载/浏览器模式
• 使用 wails build 和平台专用标志构建生产二进制文件
• 使用运行时 API（窗口、菜单、对话框、事件、日志、浏览器、剪贴板、屏幕、拖放）
• 根据需要配置 wails.json 和应用选项
• 应用前端脚本注入规则并设置外部开发服务器
• 使用平台专属打包、签名和故障排查指南
• 提供 CLI、选项、菜单、项目配置和运行时参考的链接

何时使用我

在创建 Wails 应用、本地开发、解决构建问题和使用 CLI 时，使用此技能。 如果平台、模板或 Wails 版本不明确，请提出澄清问题。

工作流

1. 确定目标操作系统和 Wails 版本。
2. 确认所需环境：Go 1.21+、Node/NPM 和平台依赖项（xcode、WebView2、GTK/WebKit）。
3. 对于新应用，选择模板并运行 wails init -n <name> -t <template>。
4. 对于开发，使用 wails dev，并说明浏览器开发服务器地址为 http://localhost:34115。
5. 对于构建，使用 wails build；在较新的 Linux 发行版上，需要时添加 -tags webkit2_41。
6. 使用运行时功能时，在 Go 中使用运行时包 github.com/wailsapp/wails/v2/pkg/runtime，或在 JS 中使用 window.runtime。
7. 对于事件，优先使用 EventsOn、EventsOnce、EventsOnMultiple、EventsOff 和 EventsEmit 来协调 Go/JS。
8. 如果出现问题，运行 wails doctor 并解决缺失的依赖项。

架构

• Wails 是一款带有 WebView 前端和共享运行时库的 Go 应用。
• Go 方法会绑定并通过自动生成的 wailsjs 模块暴露给 JS。
• 在 Go 中可通过 runtime 使用运行时方法，在 JS 中可通过 window.runtime 使用。

关键命令

go install github.com/wailsapp/wails/v2/cmd/wails@latest
wails doctor
wails init -n myproject -t <template>
wails dev
wails build

CLI 重点

• wails init：-t 指定模板（本地模板或远程 GitHub URL），-n 指定名称，-d 指定目录，-ide。
• wails dev：-assetdir、-wailsjsdir、-frontenddevserverurl、-browser、-loglevel。
• wails build：-platform、-tags、-obfuscated、-upx、-nsis、-devtools、-debug。
• wails generate module：重新生成 wailsjs，无需运行 dev。
• wails generate template：从前端项目搭建或衍生模板。

运行时 API 一览

• 事件：EventsOn、EventsOff、EventsOnce、EventsOnMultiple、EventsEmit。
• 日志：LogTrace、LogDebug、LogInfo、LogWarning、LogError、LogFatal、LogSetLogLevel。
• 窗口：标题、大小、位置、全屏/最大化/最小化、显示/隐藏、重新加载、执行 JS。
• 对话框：打开/保存对话框、消息对话框（仅 Go）。
• 菜单：设置/更新应用菜单（仅 Go）。
• 浏览器：在系统浏览器中打开 URL。
• 剪贴板：获取/设置文本。
• 屏幕：列出已连接的屏幕。
• 拖放：OnFileDrop、OnFileDropOff（需要 EnableFileDrop）。

配置和选项

• wails.json：前端目录/构建脚本、assetdir、重载目录、开发服务器 URL、输出名称、构建标签、钩子、信息/关联/协议、绑定的 ts 生成。
• 应用选项：窗口大小、边框、启动状态、背景、始终置顶、菜单、日志、回调、绑定、单实例锁、拖放、默认上下文菜单、防欺诈检测。
• 操作系统专属选项：Windows（WebView2、主题、背景效果、缩放），Mac（标题栏、外观、透明度、关于），Linux（图标、GPU 策略）。

前端集成

• 默认脚本注入会将 /wails/ipc.js 和 /wails/runtime.js 添加到 index.html。
• 使用 <meta name="wails-options" content="noautoinject"> 选择退出自动注入，并手动注入。
• 对于外部开发服务器（例如 CRA），配置 frontend:dev:watcher 和 frontend:dev:serverUrl。

指南速览

• Angular：为 ng 设置 frontend:build、frontend:install、frontend:dev:watcher、frontend:dev:serverUrl。
• 路由：优先使用基于 hash 的路由（Vue hash、Angular useHash、React HashRouter、Svelte SPA router）。
• 无边框：设置 Frameless: true，使用 --wails-draggable:drag 和 --wails-draggable:no-drag。
• 滚动回弹：使用 html { height: 100%; overflow: hidden; } 禁用回弹。
• 动态资源：使用 AssetServer.Handler 提供回退内容或动态内容（注意 Vite v5 警告）。
• 混淆：使用 wails build -obfuscated，可选添加 -garbleargs，并依赖 wailsjs 绑定。
• 单实例锁：使用带有 UniqueId 和 OnSecondInstanceLaunch 的 SingleInstanceLock。
• 自定义协议和文件关联：定义 info.protocols / info.fileAssociations，并按平台进行特定配置。
• NSIS 安装程序：安装 NSIS，然后使用 wails build -nsis 构建。
• 在 Wails master/PR 上进行本地开发：从克隆的仓库运行 go install，并在 go.mod 中使用 replace。
• Linux 注意事项：发行版软件包支持、媒体所需的 GStreamer 插件、NixOS 字体大小解决方法。
• IDE：使用 -ide vscode 或 -ide goland；调整 VS Code 任务以构建前端。
• 教程：Hello World 和 Dogs API 展示了基本的初始化、构建和开发流程。

分步操作指南

Angular 开发服务器

1. 在 wails.json 中将 frontend:build 设置为 npx ng build，将 frontend:install 设置为 npm install。
2. 添加 frontend:dev:watcher = npx ng serve 和 frontend:dev:serverUrl = http://localhost:4200。
3. 运行 wails dev。

SvelteKit 集成

1. 运行 wails init -n <name> -t svelte。
2. 删除 frontend/，然后运行 npx sv create frontend。
3. 在 wails.json 中添加 "wailsjsdir": "./frontend/src/lib"，并更新包管理器命令。
4. 在 main.go 中将 //go:embed all:frontend/dist 改为 //go:embed all:frontend/build。
5. 将 .gitignore 中的 frontend/dist 更新为 frontend/build。
6. 在 frontend/ 中安装依赖，并将适配器替换为 @sveltejs/adapter-static。
7. 添加 src/routes/+layout.ts，内容为 export const prerender = true 和 export const ssr = false。
8. 运行 wails dev。

无边框窗口拖动区域

1. 在 options.App 中设置 Frameless: true。
2. 在容器上使用 --wails-draggable:drag。
3. 在交互元素上使用 --wails-draggable:no-drag。
4. 如果无法使用 CSS 变量，请在选项中设置 CSSDragProperty 和 CSSDragValue。

动态资源

1. 在 options.App 中配置 AssetServer.Handler。
2. 在处理器中提供缺失的资源，或处理非 GET 请求。
3. 未经授权检查，不要暴露任意文件系统路径。

混淆构建

1. 使用 wails build -obfuscated 构建（可选添加 -garbleargs）。
2. 确保前端调用使用生成的 wailsjs 绑定（而非 window.go 名称）。

单实例锁

1. 添加带有 UUID UniqueId 的 SingleInstanceLock。
2. 使用 OnSecondInstanceLaunch 处理参数并将窗口置于前台。
3. 将第二个实例的数据视为不可信输入。

自定义协议

1. 在 wails.json 中添加包含 scheme、description、role 的 info.protocols。
2. macOS：处理 Mac.OnUrlOpen。
3. Windows：使用 NSIS 安装程序；解析命令行参数或使用单实例锁。
4. Linux：通过打包（例如 nfpm）创建 .desktop 和 mime 条目。

文件关联

1. 在 wails.json 中添加包含 ext、name、iconName、description、role 的 info.fileAssociations。
2. macOS：处理 Mac.OnFileOpen。
3. Windows：使用 NSIS 安装程序；解析参数或使用单实例锁。
4. Linux：创建 mime 文件、桌面条目、图标和打包脚本。

NSIS 安装程序

1. 安装 NSIS（scoop/winget/choco/brew）。
2. 根据 wails.json 配置 build/windows/installer 信息。
3. 运行 wails build -nsis，并使用 build/bin 输出。

针对 Wails master/PR 进行本地开发

1. 克隆 github.com/wailsapp/wails，切换到目标分支/PR。
2. cd v2/cmd/wails && go install。
3. 在应用的 go.mod 中添加 replace github.com/wailsapp/wails/v2 => <clonedir>/wails/v2。
4. 重新安装来自 @latest 的 CLI 并移除 replace，即可还原。

扩展指南

代码签名（Windows）

1. 将 .pfx/.p12 证书编码为 Base64，并将其存储为 GitHub Actions 密钥。
2. 在 CI 中构建应用，然后使用 signtool.exe，指定 /fd sha256 和时间戳服务器。
3. 如果使用 Actions，请确保签名步骤在 wails build 之后运行。

代码签名（macOS）

1. 导出 Apple Developer 证书（.p12）并将其编码为 Base64。
2. 使用 gon 进行签名和公证；配置 build/darwin/gon-sign.json 和授权项。
3. 通过 Apple-Actions/import-codesign-certs@v1 导入证书，然后运行 gon。

提交到 Mac App Store

1. 创建 App ID、证书、预置描述文件和 App Store Connect 条目。
2. 添加包含 App Sandbox 设置的 build/darwin/entitlements.plist。
3. 使用 wails build -platform darwin/universal 构建并签名，然后运行 codesign 和 productbuild。
4. 通过 Transporter 上传，并在 App Store Connect 中关联构建版本。

使用 GitHub Actions 进行跨平台构建

1. 使用矩阵构建 linux/amd64、windows/amd64 和 darwin/universal。
2. 缓存 node 和 Go 依赖；如有需要，设置 NODE_OPTIONS=--max-old-space-size=4096。
3. 运行 wails build（或 dAppServer/wails-build-action），并上传 build/bin/*。

WebView2 策略（Windows）

1. 使用 wails build -webview2 <download|embed|browser|error>。
2. 若要使用固定运行时，请设置 WebviewBrowserPath 并打包该运行时。
3. 如果以管理员身份运行，请将 WebviewUserDataPath 设置为共享位置。

手动构建流程（分解步骤）

1. 安装前端依赖（除非使用 -s 或没有 frontend:install）。
2. 构建前端（除非使用 -s 或没有 frontend:build）。
3. 生成资源/图标（Windows 使用 winicon 和 winres）。
4. 编译 Go（开发环境使用带 -gcflags 的 -tags dev，生产环境使用 -tags desktop,production）。
5. 可选：使用 UPX 压缩（-upx）。

模板

1. 使用 wails generate template -name <name> 搭建模板。
2. 对于现有前端，使用 -frontend 路径并更新模板文件。
3. 使用 wails init -t <path> 初始化，然后运行 wails build 进行测试。
4. 发布到 GitHub，并提交到 Community Templates。

IDE 设置

1. 使用 wails init -ide vscode 或 -ide goland。
2. 对于 VS Code，请更新 .vscode/tasks.json，加入前端安装/构建步骤。
3. 对于 Vue + Vetur，请添加指向 frontend/ 的 vetur.config.js。

故障排查要点

1. 白屏：确认存在 //go:embed all:frontend/dist，且 frontend/dist 中有资源。
2. macOS 空白屏幕：向 Info.plist 添加 NSAllowsLocalNetworking。
3. Windows 图标缓存：删除 %LOCALAPPDATA%/IconCache.db。
4. 可变参数：将数组传递给后端，不要使用展开语法。
5. 卡在 bindings：确保应用在 wails.Run() 后退出。
6. macOS 编译错误：更新 Xcode CLI 工具，或切换工具链路径。
7. 缺少 WebView2：安装正确架构的运行时。

路由模式

1. Vue：createWebHashHistory()。
2. Angular：RouterModule.forRoot(routes, { useHash: true })。
3. React：HashRouter。
4. Svelte：svelte-spa-router。

鼠标按键（无边框应用）

1. 使用 mousedown 监听器，并检查 event.button 获取按键索引。

NixOS 字体大小问题

1. 在 devShell 钩子中添加 XDG_DATA_DIRS 和 GIO_MODULE_DIR。

说明

• Wails 会为前端调用生成 Go 绑定和 TypeScript 模型。
• 项目布局包括 main.go、frontend/、build/ 和 wails.json。
• 运行时方法需要从 OnStartup 或 OnDomReady 获取上下文。
• 可以从 Go 或 JavaScript 发出事件，并可选择附带数据载荷。
• 手动构建流程为：安装 -> 构建前端 -> 生成资源 -> 编译 -> 可选使用 UPX。
• 可以通过 -webview2 策略或固定运行时处理 Windows WebView2。
• 有关代码签名、提交到 Mac App Store 和使用 GitHub Actions 构建，请参阅相关指南。
• 有关详情，请参阅 CLI、选项、菜单、项目配置和运行时参考。