` 四处，修改时需同步。 ## 功能 | 功能 | 说明 | 可用平台 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ | | 回收 Docker WSL2 磁盘空间 | 退出 Docker Desktop →`wsl --shutdown` → `diskpart` 压缩 `ext4.vhdx`，回收删除镜像/缓存后 WSL2 未归还的空间 | 仅 Windows（WSL2） | 非 Windows 平台可以正常构建和运行，但空间回收会在环境检查阶段提示不支持。 ## 环境要求 ### 通用 | 组件 | 版本 | 验证 | | --------- | -------------------------------------------------------- | ----------------- | | Go | 1.21+（本项目`go.mod` 声明 1.25.0） | `go version` | | Node.js | 15+（建议 LTS，实测 v22） | `node -v` | | npm | 随 Node 附带 | `npm -v` | | Wails CLI | **v2.15.0**（需与 `go.mod` 中的 wails 版本一致） | `wails version` | 安装 Wails CLI： ```bash go install github.com/wailsapp/wails/v2/cmd/wails@v2.15.0 ``` > 必须把 `$(go env GOPATH)/bin`（Windows 为 `%USERPROFILE%\go\bin`）加入 `PATH`，否则会提示 `wails` 命令不存在。装完先跑一次自检，它会列出缺失依赖并给出对应发行版的安装命令： ```bash wails doctor ``` ### Windows - **WebView2 Runtime**：Windows 11 及较新的 Windows 10 已内置；缺失时到 [WebView2 下载页](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) 安装。 - 可选： - [NSIS](https://nsis.sourceforge.io/) —— 生成 Windows 安装程序（`-nsis`） - [UPX](https://upx.github.io/) —— 压缩最终二进制（`-upx`） ### macOS ```bash xcode-select --install ``` - 开发需 macOS 10.15+，发布产物可支持 10.13+ - Apple Silicon（ARM64）需 macOS 11.0+ ### Linux 需要 `gcc` 工具链 + `libgtk-3` + `libwebkit2`： ```bash # Debian / Ubuntu（≤ 23.10） sudo apt update && sudo apt install -y build-essential libgtk-3-dev libwebkit2gtk-4.0-dev # Ubuntu 24.04+ / 新版 Debian（仓库里只有 4.1） sudo apt install -y build-essential libgtk-3-dev libwebkit2gtk-4.1-dev # Fedora / RHEL sudo dnf install -y gcc-c++ gtk3-devel webkit2gtk4.1-devel # Arch / Manjaro sudo pacman -S --needed base-devel gtk3 webkit2gtk-4.1 ``` > 不确定装哪个就先执行 `wails doctor`，它会针对你的发行版给出确切命令。 > 使用 `libwebkit2gtk-4.1-dev` 的发行版，构建时需额外加标签：`wails build -tags webkit2_41`。 ## 开发在项目根目录执行： ```bash wails dev ``` 它会按需安装前端依赖 → 启动 Vite 监听前端改动并热重载 → 编译并拉起桌面窗口。同时会在 http://localhost:34115 暴露 dev server，用普通浏览器打开即可在 devtools 里直接调用绑定的 Go 方法。 ### 只跑前端 ```bash cd frontend npm install # 首次 npm run dev ``` 这种方式没有 Go 后端。`frontend/wailsjs/` 下的绑定文件已生成并提交，前端可独立预览，但调用 Go 方法会失败。 ### 新增后端方法 1. 在 `app.go` 的 `App` 结构体上添加**导出方法**（首字母大写）； 2. 重新生成绑定： ```bash wails generate module ``` > `wails dev` / `wails build` 会自动重新生成，一般无需手动执行。`frontend/wailsjs/` 是生成目录，不要手改。 > 小写方法（如 `startup`）会被 Wails 当作生命周期钩子，不会暴露给前端。 ## 构建 ```bash # 仓库根目录 wails build ``` `wails build` 会自动执行 `npm install` 与 `npm run build`，再编译 Go 并嵌入前端，产物输出到 `build/bin`。 ### 常用参数 | 参数 | 作用 | | -------------------------- | ----------------------------------------------------------------------------------- | | `-clean` | 构建前清空`build/bin` | | `-o <name>` | 指定输出文件名 | | `-nsis` | 额外生成 Windows 安装程序（需装 NSIS） | | `-upx` | 用 UPX 压缩二进制（需装 UPX） | | `-trimpath` | 去掉二进制中的本地路径信息 | | `-platform <os/arch>` | 指定目标平台，逗号分隔多个 | | `-webview2 <策略>` | Windows 的 WebView2 处理：`download`（默认）/ `embed` / `browser` / `error` | | `-windowsconsole` | Windows 下保留控制台窗口（调试用） | | `-debug` / `-devtools` | 调试构建 / 生产构建保留 devtools | | `-s` | 跳过前端构建（前端无改动时提速） | | `-m` | 跳过`go mod tidy` | ### Windows（PowerShell / CMD） ```powershell wails build -clean wails build -clean -nsis # 同时生成安装包 ``` 产物：`build/bin/personal-toolbox.exe`；安装包为 `build/bin/personal-toolbox-amd64-installer.exe`。 > `-nsis` 要求本机装有 NSIS 且 `makensis.exe` 在 PATH 中。安装脚本位于 `build/windows/installer/`。 ### macOS（Terminal） ```bash wails build -clean # 当前芯片架构 wails build -clean -platform darwin/universal # amd64 + arm64 通用包 ``` 产物：`build/bin/personal-toolbox.app`（`.app` 是目录，分发时请整体压缩）。 ### Linux ```bash wails build -clean wails build -clean -tags webkit2_41 # Ubuntu 24.04+ 等只有 webkit2gtk-4.1 的发行版 ``` 产物：`build/bin/personal-toolbox`（无扩展名的 ELF 可执行文件）。 ### 关于交叉编译 Wails v2 应用依赖 CGO 与各平台原生 WebView，**不支持**直接交叉编译（例如在 macOS 上 `wails build -platform windows/amd64` 会失败）。三种可行做法： 1. **在目标系统上原生构建**（推荐，最稳）； 2. 用 CI（如 GitHub Actions）为每个平台起对应系统的 runner 分别构建； 3. 需要单机出全平台产物时使用社区 Docker 方案（如 `wailsapp/xgo`），属实验性质，排错成本高。 ## 目录结构 ``` . ├── main.go # 入口：窗口配置 + Bind 注册 + 嵌入 frontend/dist ├── app.go # App 结构体与对外暴露的方法 ├── docker_wsl.go # Docker WSL2 空间回收实现 ├── wails.json # 项目配置（名称、产物名、前后端命令） ├── frontend/ │ ├── src/ # Vue 3 源码（components / assets / style.css） │ ├── wailsjs/ # 自动生成，勿手改 │ └── dist/ # 前端构建产物，已被 gitignore └── build/ ├── appicon.png # 图标源文件 ├── windows/ # 图标、manifest、NSIS 安装脚本 ├── darwin/ # Info.plist └── bin/ # 构建输出（已 gitignore） ``` ## 常见问题 **`go build ./...` 报 `pattern all:frontend/dist: no matching files found`** `frontend/dist` 被 `.gitignore` 忽略，但 `main.go` 的 `//go:embed all:frontend/dist` 依赖它。全新克隆后必须先构建前端，或直接用 `wails build` / `wails dev`（它们会自动跑 `npm install` + `npm run build`）。 **提示 `wails` 命令找不到** `$(go env GOPATH)/bin` 未加入 `PATH`，添加后重开终端。 **Windows 下 `wails build` 报 `unlinkat ...\personal-toolbox.exe: Access is denied`** 旧的可执行文件正在运行，文件被系统锁定无法覆盖。关闭正在运行的程序后重新构建；或先用 `wails build -o <其他名字>` 输出到新文件名。也可用 `-clean` 前先确认进程已退出。 **Windows 启动白屏或报 WebView2 错误** 缺少 WebView2 Runtime。安装它，或用 `wails build -webview2 embed` 把引导程序打进产物。 **执行空间回收时弹 UAC 窗口** 正常现象，`diskpart` 压缩虚拟磁盘需要管理员权限。程序本身不需要以管理员身份运行：已提权则直接执行，未提权时通过 UAC 临时提权。若 UAC 弹不出来（标准账户或策略禁用），请右键"以管理员身份运行"本程序后重试。 **「回收空间」按钮是灰的** 顶部环境检查未全部通过：需要 Windows + 已安装 Docker Desktop + WSL 可用。三项均满足且扫描到 `.vhdx` 后按钮才可点击。

# personal-toolbox **Repository Path**: leihenshang/personaltoolbox ## Basic Information - **Project Name**: personal-toolbox - **Description**: 工具箱 - **Primary Language**: Go - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2022-09-22 - **Last Updated**: 2026-09-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # personal-toolbox 基于 [Wails v2](https://wails.io/) 的桌面小工具箱：Go 1.25 后端 + Vue 3 前端，编译为单个原生可执行文件。 > 项目名刻意拼写为 `personal-toolbox`（不是 personal）。它同时出现在 `go.mod` 的 module 名、`wails.json` 的 `name`/`outputfilename`、`main.go` 的 `Title` 和 `frontend/index.html` 的 `` 四处，修改时需同步。 ## 功能 | 功能 | 说明 | 可用平台 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ | | 回收 Docker WSL2 磁盘空间 | 退出 Docker Desktop →`wsl --shutdown` → `diskpart` 压缩 `ext4.vhdx`，回收删除镜像/缓存后 WSL2 未归还的空间 | 仅 Windows（WSL2） | 非 Windows 平台可以正常构建和运行，但空间回收会在环境检查阶段提示不支持。 ## 环境要求 ### 通用 | 组件 | 版本 | 验证 | | --------- | -------------------------------------------------------- | ----------------- | | Go | 1.21+（本项目`go.mod` 声明 1.25.0） | `go version` | | Node.js | 15+（建议 LTS，实测 v22） | `node -v` | | npm | 随 Node 附带 | `npm -v` | | Wails CLI | **v2.15.0**（需与 `go.mod` 中的 wails 版本一致） | `wails version` | 安装 Wails CLI： ```bash go install github.com/wailsapp/wails/v2/cmd/wails@v2.15.0 ``` > 必须把 `$(go env GOPATH)/bin`（Windows 为 `%USERPROFILE%\go\bin`）加入 `PATH`，否则会提示 `wails` 命令不存在。装完先跑一次自检，它会列出缺失依赖并给出对应发行版的安装命令： ```bash wails doctor ``` ### Windows - **WebView2 Runtime**：Windows 11 及较新的 Windows 10 已内置；缺失时到 [WebView2 下载页](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) 安装。 - 可选： - [NSIS](https://nsis.sourceforge.io/) —— 生成 Windows 安装程序（`-nsis`） - [UPX](https://upx.github.io/) —— 压缩最终二进制（`-upx`） ### macOS ```bash xcode-select --install ``` - 开发需 macOS 10.15+，发布产物可支持 10.13+ - Apple Silicon（ARM64）需 macOS 11.0+ ### Linux 需要 `gcc` 工具链 + `libgtk-3` + `libwebkit2`： ```bash # Debian / Ubuntu（≤ 23.10） sudo apt update && sudo apt install -y build-essential libgtk-3-dev libwebkit2gtk-4.0-dev # Ubuntu 24.04+ / 新版 Debian（仓库里只有 4.1） sudo apt install -y build-essential libgtk-3-dev libwebkit2gtk-4.1-dev # Fedora / RHEL sudo dnf install -y gcc-c++ gtk3-devel webkit2gtk4.1-devel # Arch / Manjaro sudo pacman -S --needed base-devel gtk3 webkit2gtk-4.1 ``` > 不确定装哪个就先执行 `wails doctor`，它会针对你的发行版给出确切命令。 > 使用 `libwebkit2gtk-4.1-dev` 的发行版，构建时需额外加标签：`wails build -tags webkit2_41`。 ## 开发在项目根目录执行： ```bash wails dev ``` 它会按需安装前端依赖 → 启动 Vite 监听前端改动并热重载 → 编译并拉起桌面窗口。同时会在 http://localhost:34115 暴露 dev server，用普通浏览器打开即可在 devtools 里直接调用绑定的 Go 方法。 ### 只跑前端 ```bash cd frontend npm install # 首次 npm run dev ``` 这种方式没有 Go 后端。`frontend/wailsjs/` 下的绑定文件已生成并提交，前端可独立预览，但调用 Go 方法会失败。 ### 新增后端方法 1. 在 `app.go` 的 `App` 结构体上添加**导出方法**（首字母大写）； 2. 重新生成绑定： ```bash wails generate module ``` > `wails dev` / `wails build` 会自动重新生成，一般无需手动执行。`frontend/wailsjs/` 是生成目录，不要手改。 > 小写方法（如 `startup`）会被 Wails 当作生命周期钩子，不会暴露给前端。 ## 构建 ```bash # 仓库根目录 wails build ``` `wails build` 会自动执行 `npm install` 与 `npm run build`，再编译 Go 并嵌入前端，产物输出到 `build/bin`。 ### 常用参数 | 参数 | 作用 | | -------------------------- | ----------------------------------------------------------------------------------- | | `-clean` | 构建前清空`build/bin` | | `-o <name>` | 指定输出文件名 | | `-nsis` | 额外生成 Windows 安装程序（需装 NSIS） | | `-upx` | 用 UPX 压缩二进制（需装 UPX） | | `-trimpath` | 去掉二进制中的本地路径信息 | | `-platform <os/arch>` | 指定目标平台，逗号分隔多个 | | `-webview2 <策略>` | Windows 的 WebView2 处理：`download`（默认）/ `embed` / `browser` / `error` | | `-windowsconsole` | Windows 下保留控制台窗口（调试用） | | `-debug` / `-devtools` | 调试构建 / 生产构建保留 devtools | | `-s` | 跳过前端构建（前端无改动时提速） | | `-m` | 跳过`go mod tidy` | ### Windows（PowerShell / CMD） ```powershell wails build -clean wails build -clean -nsis # 同时生成安装包 ``` 产物：`build/bin/personal-toolbox.exe`；安装包为 `build/bin/personal-toolbox-amd64-installer.exe`。 > `-nsis` 要求本机装有 NSIS 且 `makensis.exe` 在 PATH 中。安装脚本位于 `build/windows/installer/`。 ### macOS（Terminal） ```bash wails build -clean # 当前芯片架构 wails build -clean -platform darwin/universal # amd64 + arm64 通用包 ``` 产物：`build/bin/personal-toolbox.app`（`.app` 是目录，分发时请整体压缩）。 ### Linux ```bash wails build -clean wails build -clean -tags webkit2_41 # Ubuntu 24.04+ 等只有 webkit2gtk-4.1 的发行版 ``` 产物：`build/bin/personal-toolbox`（无扩展名的 ELF 可执行文件）。 ### 关于交叉编译 Wails v2 应用依赖 CGO 与各平台原生 WebView，**不支持**直接交叉编译（例如在 macOS 上 `wails build -platform windows/amd64` 会失败）。三种可行做法： 1. **在目标系统上原生构建**（推荐，最稳）； 2. 用 CI（如 GitHub Actions）为每个平台起对应系统的 runner 分别构建； 3. 需要单机出全平台产物时使用社区 Docker 方案（如 `wailsapp/xgo`），属实验性质，排错成本高。 ## 目录结构 ``` . ├── main.go # 入口：窗口配置 + Bind 注册 + 嵌入 frontend/dist ├── app.go # App 结构体与对外暴露的方法 ├── docker_wsl.go # Docker WSL2 空间回收实现 ├── wails.json # 项目配置（名称、产物名、前后端命令） ├── frontend/ │ ├── src/ # Vue 3 源码（components / assets / style.css） │ ├── wailsjs/ # 自动生成，勿手改 │ └── dist/ # 前端构建产物，已被 gitignore └── build/ ├── appicon.png # 图标源文件 ├── windows/ # 图标、manifest、NSIS 安装脚本 ├── darwin/ # Info.plist └── bin/ # 构建输出（已 gitignore） ``` ## 常见问题 **`go build ./...` 报 `pattern all:frontend/dist: no matching files found`** `frontend/dist` 被 `.gitignore` 忽略，但 `main.go` 的 `//go:embed all:frontend/dist` 依赖它。全新克隆后必须先构建前端，或直接用 `wails build` / `wails dev`（它们会自动跑 `npm install` + `npm run build`）。 **提示 `wails` 命令找不到** `$(go env GOPATH)/bin` 未加入 `PATH`，添加后重开终端。 **Windows 下 `wails build` 报 `unlinkat ...\personal-toolbox.exe: Access is denied`** 旧的可执行文件正在运行，文件被系统锁定无法覆盖。关闭正在运行的程序后重新构建；或先用 `wails build -o <其他名字>` 输出到新文件名。也可用 `-clean` 前先确认进程已退出。 **Windows 启动白屏或报 WebView2 错误** 缺少 WebView2 Runtime。安装它，或用 `wails build -webview2 embed` 把引导程序打进产物。 **执行空间回收时弹 UAC 窗口** 正常现象，`diskpart` 压缩虚拟磁盘需要管理员权限。程序本身不需要以管理员身份运行：已提权则直接执行，未提权时通过 UAC 临时提权。若 UAC 弹不出来（标准账户或策略禁用），请右键"以管理员身份运行"本程序后重试。 **「回收空间」按钮是灰的** 顶部环境检查未全部通过：需要 Windows + 已安装 Docker Desktop + WSL 可用。三项均满足且扫描到 `.vhdx` 后按钮才可点击。