u-desk/docs/04-功能迭代/GO-DESK-8.Wails-v3迁移.md

GO-DESK-8: Wails v3 迁移变更分析

范围: 44847e0(v0.4.0) → f54bf1c(fs-only-v3) | 提交数: 1 | 日期: 2026-05-01

变更总览

类别	数量	说明
重命名	77	web/ → frontend/（git rename，历史保留）
新增	94	v3 构建模板 + bindings + 新文件
删除	4	旧文件（clipboard png、md5、v2 transport/types）
修改	10	核心代码适配 v3 API
合计	185	+7,772 / -918 行

---

一、框架升级（核心）

Wails v2 → v3 API 映射

v2 (旧)	v3 (新)	文件
wails.Run(&options.App{...})	application.New() + Window.NewWithOptions()	main.go
options.App.Bind: []interface{}{app}	Services: []application.Service{application.NewService(app)}	main.go
AssetServer: &assetserver.Options{}	Assets: application.AssetOptions{Handler, Middleware}	main.go
app.Startup(ctx) / app.Shutdown(ctx)	app.ServiceStartup(ctx, opts) / app.ServiceShutdown()	app.go
runtime.Window(ctx)	a.mainWindow（手动注入）	app.go
runtime.* 函数调用	window.* 方法 + v3-bindings 自动生成	前端
//go:embed all:web/dist	//go:embed all:frontend/dist	main.go

main.go 实质性变更

• Middleware 中间件: 拦截 /wails/custom.js 返回空 200，消除控制台 404
• DevTools: 延迟 2s 调用 window.OpenDevTools()（production + devtools build tag）
• 窗口主题: Windows CustomTheme 配置亮/暗模式标题栏颜色

app.go 实质性变更

• 新增 SetMainWindow() — v3 需要手动注入窗口引用
• 新增 SetWindowTitleBarColor() — v3 窗口主题色动态切换
• 新增 sync.Mutex — 并发安全保护 mainWindow
• 生命周期: Startup/Shutdown → ServiceStartup/ServiceShutdown（返回 error）
• 错误处理: panic → return error（符合 Go 惯例）

---

二、前端代码修改（有业务逻辑变化的）

App.vue (+375/-60 行)

• Tabs padding-top 覆盖（Arco Design 默认 16px → 0）
• import 路径更新：@/wailsjs/v3-bindings/u-desk/app
• 窗口控制方法改用 v3 binding 导入

Sidebar.vue (+406 行)

• 新架构: 双区块折叠（收藏夹 + 帮助文档），各自独立 header + content
• 滚动优化: .sidebar overflow:hidden + 收藏内容区 overflow-y:auto 内部滚动
• 帮助区块: 固定底部 flex-shrink:0，默认展开
• 折叠动画: max-height + opacity CSS transition

useFavorites.ts (+259 行)

• 修复: longPressTimer const → let（解决 Assignment to constant variable TypeError）

stores/ (config/theme/update)

• config.ts: Wails v3 绑定加载方式调整
• theme.ts: 窗口主题色通过 v3 API 设置
• update.ts: 更新检查逻辑适配 v3 事件系统

wails-transport.ts (+121 行)

• 全新: v3 transport 层实现（替代 v2 的 runtime 调用）

UpdateNotification.vue / UpdatePanel.vue

• 事件监听从 v2 runtime 改为 v3 OffAll/events 模式

---

三、依赖变更

- github.com/wailsapp/wails/v2 v2.12.0
+ github.com/wailsapp/wails/v3 v3.0.0-alpha.80

- go 1.25.6
+ go 1.26

+ github.com/wailsapp/wails/v3/pkg/w32     # Win32 直接调用
+ dario.cat/mergo v1.0.2                    # 结构体合并

移除: go-toast/v2（v3 自带通知）、gosod/slicer（v2 工具库）

---

四、新增构建基础设施（94 个文件，均为 Wails v3 标准模板）

以下由 wails3 task generate 自动生成，无自定义逻辑：

目录	用途
build/config.yml	项目配置（dev mode executes 流水线）
Taskfile.yml	根级任务定义（dev/build/run）
build/android/	Android 构建模板（Gradle + Java Bridge）
build/darwin/	macOS 构建（Info.plist + Icons）
build/ios/	iOS 构建（Xcode project）
build/linux/	Linux 构建（AppImage + nfpm）
build/docker/	Docker 交叉编译
build/windows/nsis/	NSIS 安装包脚本
build/windows/msix/	MSIX 打包配置
frontend/src/wailsjs/v3-bindings/	v3 TypeScript 绑定（自动生成）
frontend/bindings/	v3 绑定副本（备用路径）

---

五、删除项（4 个文件）

文件	原因
cmd/agent/clipboard_*.png	截图残留，已归档到 .archive/
web/package.json.md5	旧完整性校验文件
web/src/api/wails-transport.ts	v2 版本，已被 frontend 下新版替代
web/src/types/window.d.ts	v2 类型声明，已被 frontend 下新版替代

---

六、风险点

1. alpha.80 稳定性: Wails v3 仍为 alpha，部分 API 可能后续 breaking change
2. OpenDevTools sleep hack: 2s 硬编码延迟不够可靠，待 OnDomReady 稳定后替换
3. v2 bindings 残留: frontend/src/wailsjs/wailsjs/（v2）仍随重命名保留在 frontend/ 下，如不再使用应清理