lxy/u-desk
Private
Public Access
1
0
Fork 0
Code Activity
Files
2a363fd7292f6bb5ac5ca4895454909ba5b6fd20
u-desk/docs/04-功能迭代/GO-DESK-8.Wails-v3迁移
History

README.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/ 下，如不再使用应清理
View Git Blame Copy Permalink