127 lines
4.9 KiB
Markdown
127 lines
4.9 KiB
Markdown
# 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 模式
|
||
|
||
---
|
||
|
||
## 三、依赖变更
|
||
|
||
```diff
|
||
- 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/ 下，如不再使用应清理
|