开发指南

Windows 的 MSYS2 安装与编译器配置参考 DuckDB Go 官方文档的 Windows 要求。项目需要正确版本的 GCC 和相应运行库，并启用 CGO。

使用 MSYS2 安装程序完成安装，然后打开 MSYS2 终端并执行官方要求的安装命令：

pacman -S mingw-w64-ucrt-x86_64-gcc

根据安装提示确认操作。如果终端在安装过程中关闭，请重新打开终端完成安装。

AMD64 环境中，编译器目标应包含 x86_64，CGO 值应为 1，Go 架构应为 amd64。可以将编译器目录加入 Windows 用户的 Path 环境变量。

配置 WebView2 和 NSIS

安装 WebView2 Evergreen Runtime，供 Wails 桌面窗口加载前端。构建安装包时，还需安装 NSIS，NSIS 用于 installer 和 all 打包模式，便携包使用 portable 模式。

克隆项目

git clone https://github.com/Saramanda9988/LunaBox.git
Set-Location LunaBox

后续命令均在项目根目录执行。

安装匹配的 Wails v3 CLI

从当前检出的源码读取 Wails 版本并安装 CLI：

$wailsVersion = (go list -m -f '{{.Version}}' github.com/wailsapp/wails/v3).Trim()
go install "github.com/wailsapp/wails/v3/cmd/wails3@$wailsVersion"

当前仓库使用 v3.0.0-beta.5。随着依赖更新，以上命令会使用对应版本。发布脚本会检查 CLI 与项目依赖的版本是否相同。

wails3 version
wails3 doctor

根据 wails3 doctor 的检查结果补齐平台依赖，安装方法参见 Wails v3 官方安装文档。

安装依赖并准备前端资源

go mod download
go -C updater mod download
pnpm --dir frontend install --frozen-lockfile
wails3 generate bindings -clean=true -ts
pnpm --dir frontend build

主程序通过 go:embed 嵌入 frontend/dist，首次启动前先构建前端，确保嵌入资源存在。updater 是仓库内独立的 Go 模块，发布打包时会构建更新程序。

Wails 自动生成的 TypeScript 绑定位于 frontend/bindings/。修改后端服务方法或类型后，通过生成命令更新该目录，业务代码使用具体服务绑定文件或 frontend/src/bindings/ 兼容入口。

在配置好 CGO 的 PowerShell 终端中执行：

wails3 dev

该任务使用 build/config.yml 启动 Wails v3 开发模式，生成绑定、构建开发程序、启动 Vite 服务并打开桌面窗口。Vite 默认端口为 9245，前端修改由 Vite 热更新，Go 文件修改会触发程序重新构建。

发布脚本参数格式为 scripts\build.bat [构建模式] [版本号] [目标架构]。目标架构支持 amd64 和 arm64，默认使用 amd64。

以 1.12.1 为示例版本，先更新 Windows 版本资源，再生成发布包：

.\scripts\update-build-assets.bat 1.12.1
.\scripts\build.bat all 1.12.1 amd64

update-build-assets.bat 更新 build/config.yml 和平台构建资源中的版本信息，接受 X.Y.Z 格式及可选的 v 前缀。构建其他版本时，请将两条命令中的版本号一并替换。

单独生成便携包或安装程序：

.\scripts\build.bat portable 1.12.1 amd64
.\scripts\build.bat installer 1.12.1 amd64

省略版本号时，脚本通过 git describe 获取最近的 v 前缀版本标签；缺少标签时使用 1.0.0。传入版本号的 v 前缀会自动移除。脚本还会注入 Git 提交哈希、构建时间和构建模式。

发布脚本自动安装锁定的前端依赖、生成 Wails v3 绑定、构建生产前端，并编译桌面程序、命令行程序和独立更新程序。请保留仓库中的 lib/winamd64/7z/7z.exe 和 7z.dll，脚本会将它们加入发布包。

生成的发布包位于 build/bin/：

build/bin/LunaBox-1.12.1-windows-amd64-portable.zip
build/bin/LunaBox-1.12.1-windows-amd64-setup.exe

Windows ARM64 打包

ARM64 打包需要面向 ARM64 的 CGO 编译器。项目发布构建在 Windows ARM64 环境中使用 MSYS2 的 CLANGARM64 工具。在该终端中安装：

pacman -S --needed mingw-w64-clang-aarch64-toolchain

在 PowerShell 中指定 MSYS2 安装目录并执行发布脚本：

$env:MSYS2_LOCATION = "C:\msys64"
.\scripts\build.bat all 1.12.1 arm64

脚本会查找 clangarm64/bin/clang.exe，配置 ARM64 编译目标，并使用仓库中的 lib/winarm64/duckdb.dll、duckdb.lib 和 lib/winarm64/7z/。请保留这些文件，ARM64 发布包会包含运行所需的 DuckDB 动态库。