Wails v2 build 目录完全指南：Darwin 与 Windows 平台构建文件的结构、定制与恢复默认

Wails v2 build 目录完全指南Darwin 与 Windows 平台构建文件的结构、定制与恢复默认【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wailsbuild/目录是每个 Wails v2 项目构建流程的核心基础设施它集中存放了应用打包所需的全部构建文件与资源并按目标平台拆分为bin输出目录、darwinmacOS 专属文件与windowsWindows 专属文件三部分。本指南将以仓库中 v2/examples/dragdrop-test/build/README.md 为骨架结合仓库内真实项目如 dragdrop-test 示例的build目录、模板文件与源码实现完整讲解每个文件的作用、模板变量的填充机制、定制方法以及如何一键恢复默认状态。build 目录的总体结构Wails v2 项目在创建时会自动生成一个build目录用于存放应用构建与分发所需的全部文件与资源。以 dragdrop-test 示例的 build 目录 为例其完整布局为build/ ├── README.md # 本指南对应的说明文档 ├── appicon.png # 应用图标源文件构建时用于生成各平台图标 ├── darwin/ │ ├── Info.plist # wails build 时使用的 macOS 主 plist │ └── Info.dev.plist # wails dev 时使用的 plist └── windows/ ├── icon.ico # Windows 应用图标 ├── info.json # Windows 版本信息文件属性详情 ├── wails.exe.manifest # 应用 manifestUAC、DPI 感知等 └── installer/ ├── project.nsi # NSIS 安装器主脚本 └── wails_tools.nsh # wails build 自动生成的安装器宏库目录中三类条目的定位如下bin构建输出目录。wails build生成的可执行文件以及--nsis安装器产物都会写入这里初始阶段该目录通常不存在首次构建时自动创建darwin存放 macOS 构建专属文件可在构建流程中被定制并使用windows存放 Windows 构建所需的 manifest 与 rc 文件同样支持按需定制。需要强调的是darwin与windows下的文件都是「可回归默认状态」的如果你修改后想还原只需删除这些文件然后重新执行wails build构建工具就会用内置模板重新生成一份默认版本模板源头见 v2/pkg/buildassets/build。Macdarwin构建文件详解Info.plist 与 Info.dev.plist 的分工darwin目录包含两个 plist 文件分别对应两种构建模式文件使用时机作用Info.plistwails buildmacOS 应用包.app的主 plist定义应用元数据、文档类型关联、URL Scheme 等Info.dev.plistwails dev与主 plist 内容基本一致但额外包含NSAppTransportSecurity配置允许开发阶段访问本地网络资源以 dragdrop-test 的 Info.plist 为例默认主 plist 的关键字段包括CFBundlePackageTypeAPPL标识这是一个应用包Application BundleCFBundleName{{.Info.ProductName}}显示的应用名CFBundleExecutable{{.OutputFilename}}可执行文件名称CFBundleIdentifiercom.wails.{{.Name}}bundle 标识符默认以com.wails.为前缀拼接项目名CFBundleVersion/CFBundleShortVersionString{{.Info.ProductVersion}}版本号CFBundleGetInfoString{{.Info.Comments}}与NSHumanReadableCopyright{{.Info.Copyright}}辅助信息与版权CFBundleIconFileiconfile应用图标LSMinimumSystemVersion10.13.0最低支持的 macOS 版本NSHighResolutionCapabletrue支持 Retina 高分屏。plist 中的模板变量与条件段这两个 plist 是 Go 模板文件构建时会依据 wails.json 配置 中的Info段ProductName、ProductVersion、CompanyName、Copyright、Comments以及项目名name、输出文件名outputfilename自动填充。值得注意的两个条件模板段{{if .Info.FileAssociations}}当项目配置了文件关联FileAssociations时模板会生成CFBundleDocumentTypes数组为每个关联扩展名生成CFBundleTypeExtensions、CFBundleTypeName、CFBundleTypeRole、CFBundleTypeIconFile等条目从而实现双击文件用本应用打开的能力{{if .Info.Protocols}}当配置了自定义 URL 协议Protocols时模板会生成CFBundleURLTypes数组将每个 Scheme 注册到CFBundleURLSchemes让系统可以把myapp://这类链接路由到应用。对比 Info.dev.plist 可以看到开发版唯一多出的内容是keyNSAppTransportSecurity/key dict keyNSAllowsLocalNetworking/key true/ /dict该配置允许开发模式下的应用访问本机网络如连接 http://localhost:34115 的前端开发服务器属于wails dev专属的便利设施。Windows 构建文件详解icon.ico 与 appicon.png 的图标生成链路windows目录下的icon.ico是应用在 Windows 下使用的图标直接用于wails build产出的 exe。定制的两种方式直接替换用你自己的.ico文件覆盖build/windows/icon.ico源文件生成如果icon.ico缺失构建时 Wails 会自动基于build/appicon.png如 示例中的 appicon.png重新生成一个icon.ico。这一行为在 v2/pkg/buildassets/build/README.mdbuildassets包内置的默认 README中有完全一致的描述If it is missing, a new icon.ico file will be created using the appicon.png file in the build directory.可见appicon.png是整个图标链路的事实源头。info.jsonWindows 版本信息info.json 存放 Windows 构建所需的版本与应用信息内容同样使用模板变量填充{ fixed: { file_version: {{.Info.ProductVersion}} }, info: { 0000: { ProductVersion: {{.Info.ProductVersion}}, CompanyName: {{.Info.CompanyName}}, FileDescription: {{.Info.ProductName}}, LegalCopyright: {{.Info.Copyright}}, ProductName: {{.Info.ProductName}}, Comments: {{.Info.Comments}} } } }该文件中的数据会被 Windows 安装器以及应用本身使用——用户在资源管理器中右键 exe → 属性 → 详细信息Details里看到的公司、产品名称、版权、文件版本等信息即来源于此。wails.exe.manifestUAC 与 DPI 感知wails.exe.manifest 是应用主 manifest 文件默认内容包含程序集标识assemblyIdentity typewin32 namecom.wails.{{.Name}} version{{.Info.ProductVersion}}.0 .../Common-Controls 依赖声明依赖Microsoft.Windows.Common-Controls6.0确保应用使用现代视觉风格控件DPI 感知声明dpiAware xmlnshttp://schemas.microsoft.com/SMI/2005/WindowsSettingstrue/pm/dpiAware dpiAwareness xmlnshttp://schemas.microsoft.com/SMI/2016/WindowsSettingspermonitorv2,permonitor/dpiAwareness其中true/pm是为 Windows 7/8 提供的回退方案permonitorv2,permonitor则优先启用 Per-Monitor V2 DPI 感知并在不支持时回退到 per-monitor保证多显示器不同缩放比例下界面清晰。installer/NSIS 安装器脚本installer目录包含创建 Windows 安装器的脚本由wails build --nsis使用project.nsi安装器主脚本见 dragdrop-test 的 project.nsi。它通过!include wails_tools.nsh引入宏库默认配置包括ManifestDPIAware true安装器自身 HiDPI 支持、安装路径$PROGRAMFILES64\${INFO_COMPANYNAME}\${INFO_PRODUCTNAME}、创建开始菜单与桌面快捷方式、卸载时清除 WebView2 数据目录与注册表项。文件头部注释明确说明脚本支持手动调用makensis调试见下文版本信息默认从 ProjectInfo 填充但也可通过!define INFO_*等覆盖。wails_tools.nsh标注DO NOT EDIT - Generated automatically by wails build的宏库由wails build在构建时自动生成模板同样位于 v2/pkg/buildassets/build/windows/installer。它提供了wails.checkArchitecture校验系统至少为 Windows 10 / Server 2016 且架构匹配、wails.webview2runtime通过注册表检测 WebView2 Runtime 是否已安装未安装则静默执行 bootstrapper、wails.files按架构复制 amd64/arm64 可执行文件、wails.associateFiles/wails.associateCustomProtocols写入文件关联与自定义协议注册表项等核心宏。手动调试安装器不经过 wails buildproject.nsi头部的注释给出了完整的独立调试流程# 1. 先用 wails 生成一份 wails_tools.nsh 填充默认值 wails build --target windows/amd64 --nsis # 2. 再用 makensis 直接构建安装器 # 仅 amd64 makensis -DARG_WAILS_AMD64_BINARY..\..\bin\app.exe # 仅 arm64 makensis -DARG_WAILS_ARM64_BINARY..\..\bin\app.exe # 双架构 makensis -DARG_WAILS_AMD64_BINARY..\..\bin\app-amd64.exe -DARG_WAILS_ARM64_BINARY..\..\bin\app-arm64.exe生成的安装器命名遵循${INFO_PROJECTNAME}-${ARCH}-installer.exeARCH为amd64、arm64或amd64_arm64输出到bin目录。如果project.nsi中未定义INFO_PROJECTNAME等宏wails_tools.nsh会自动用 ProjectInfo 的值补齐。在真实项目中实践以仓库内的 dragdrop-test 示例 为参考该项目的 wails.json 声明了项目名dragdrop-test、输出文件名dragdrop-test并配置了frontend:install、frontend:build、frontend:dev:watcher等前端命令。在项目目录下执行# 实时开发模式使用 Info.dev.plistmacOS并启动 Vite 热重载 wails dev # 生产构建使用 Info.plist / icon.ico / info.json / manifest / NSIS 等全部构建资源 wails buildwails dev会运行前端开发服务器提供极快的热重载同时会启动一个位于 http://localhost:34115 的浏览器调试服务器开发者可在浏览器中访问它并直接在 devtools 里调用 Go 方法相关绑定见 main.go 中的Bind: []interface{}{app}。wails build产出可分发、生产模式的应用包如需同时生成 Windows 安装器追加--nsis参数。macOS 构建产物基于Info.plistWindows 构建产物则基于windows目录下的图标、版本信息与 manifest并通过installer/生成 NSIS 安装包。定制与恢复默认的操作清单定制流程任选其一图标替换build/windows/icon.icoWindows或替换build/appicon.png并删除icon.ico让构建流程自动再生成macOS 元数据 / 文件关联 / URL 协议编辑build/darwin/Info.plist或在wails.json的Info段配置FileAssociations与Protocols由模板条件段自动展开Windows 版本信息修改build/windows/info.json中的字段值Windows 权限与 DPI编辑build/windows/wails.exe.manifest安装器行为编辑build/windows/installer/project.nsi如启用 EULA 页面、签名命令signtool、欢迎页位图等默认均以注释形式保留。恢复默认直接删除build/darwin与build/windows两个目录或其中被改动的文件再执行wails buildWails 将依据 v2/pkg/buildassets/build 中的内置模板重新生成全套默认文件。注意wails_tools.nsh属于自动生成物手动编辑会被下次构建覆盖如需持久改动应改在project.nsi中进行。总结build目录是 Wails v2 应用在 macOS 与 Windows 上完成「定制图标 → 填充元数据 → 注册文件关联与协议 → 打包安装器」全流程的枢纽。理解Info.plist/Info.dev.plist的分工、icon.ico与appicon.png的生成链路、info.json的版本信息来源以及project.nsi与wails_tools.nsh的协作机制即可在 dragdrop-test 这样的真实项目基础上快速打造符合自己品牌与分发需求的多平台构建产物而「删除文件 重新构建」的恢复机制也让开发者可以放心大胆地反复实验。【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考