构建与发布
用 nsgo check 验证全部目标平台,在 nsgo.yaml 中配置应用元数据、图标和签名,并用 nsgo build 为 macOS、Windows、Linux、Web、iOS 和 Android 构建发布包。
配置 nsgo.yaml
nsgo build 从项目根目录的 nsgo.yaml 读取应用标识、图标、签名和默认构建目标。命令行上的参数(-name、-id、-version、-build-number、-output、-target、-channel)会覆盖本次构建对应的 nsgo.yaml 字段。
name: My Game
id: com.example.mygame
version: 1.0.0
build_number: 1
copyright: "© 2026 Example Studio"
icon:
apple: assets/AppIcon.icon # Icon Composer .icon(macOS/iOS)或 .icns(仅 macOS)
png: assets/Icon.png # 正方形 PNG(推荐 1024x1024)
build:
output: dist
installers: true
targets:
- macos_arm64
- macos_x64
- windows_x64
- windows_arm64
- linux_x64
- linux_arm64
- web
- ios
- android_arm64
id:反向域名格式的 Bundle ID / Application ID(例如com.example.mygame)。各版本间请保持不变,Apple App Store、Google Play 和 Microsoft Store 都以此识别你的应用。version:面向用户的语义化版本号(Apple 的CFBundleShortVersionString、Android 的versionName)。build_number:每次提交商店都必须递增的整数构建号(Apple 的CFBundleVersion、Android 的versionCode)。省略时会从version推导。resources/与assets/:运行时加载的游戏资源("asset:...")放在resources/中,会原样打入每个安装包;图标等构建期输入放在assets/中,由工具转换成各平台图标格式。可以在nsgo.yaml里用mobile.exclude_resources从 iOS 和 Android 包中排除仅桌面端使用的资源。
应用图标
把默认图标放到 assets/ 目录下,nsgo build 无需额外配置即可自动识别:
assets/AppIcon.icon(Apple Icon Composer 格式)或assets/AppIcon.icns(仅 macOS),用于 macOS 和 iOS。assets/Icon.png(正方形 PNG,建议 1024×1024),用于 Windows、Linux、Android、Web,以及未配置icon.apple的 Apple 目标。
如果需要区分开发版和正式版图标,可以放置带 -dev 后缀的文件(assets/AppIcon-dev.icon、assets/Icon-dev.png)或在 dev.icon 中指定,nsgo dev 会自动使用它们。
对于桌面端安装程序,还可以在 nsgo.yaml 中设置 macos.dmg_icon、macos.dmg_background(PNG,可选同名 @2x 图)、windows.installer_icon 和 windows.uninstaller_icon。
构建前检查所有目标平台
先检查本机已安装的工具链:
go tool nsgo doctor
在构建发布包前,用 nsgo check 对所有目标平台执行 go vet(以及目录检查):
go tool nsgo check -target all
或者显式检查全部 6 个游戏平台:
go tool nsgo check -target macos,windows,linux,web,ios,android
- 传入
-jobs N可并行检查最多N个目标。 - 仅写操作系统名(
macos、windows、linux)会自动展开为arm64和x64两个架构;android展开为android_arm64(android_x64需要 Android NDK)。 - 在 Linux 或 Windows 主机上,
-target all会跳过需要 macOS 与 Xcode 的 Apple 目标;如果显式指定ios而缺少 Xcode,则会报错。
无头测试运行 go tool nsgo test;在真实平台上运行测试则使用 go tool nsgo test -target macos|windows|linux|web|ios_simulator|android。
构建发布包
nsgo build 会构建剥离调试符号的正式版二进制,在 <output>/<name>-<version>-<target> 下为每个目标生成目录,并输出可分发的发布文件。
# 按 nsgo.yaml 中配置的目标构建
go tool nsgo build
# 构建当前机器上 Go 与 Xcode 支持的全部目标
go tool nsgo build -target all
# 构建商店提交格式的包,而非直接下载的安装器
go tool nsgo build -channel store -target macos,windows,linux,ios,android
-channel 控制打包格式与更新通道:
direct(默认):直接分发安装器与压缩包(.dmg、NSIS.exe、.deb/Arch/.AppImage、.apk、.ipa、Web.zip)。store:应用商店提交包(Mac App Store.pkg、Microsoft Store.msix、Flathub.tar.gz+ Flatpak 清单、Google Play.aab、iOS.ipa)。none:跳过自动更新源配置,保留直接分发格式。
如果桌面端只需要未打包的应用目录,传入 -installers=false。传入 -run 可在构建完成后立刻在本机、连接的设备或本地 Web 服务器上运行产物。
各目标平台说明
| 平台 | 目标名 | 直接分发(-channel direct) |
商店发布(-channel store) |
构建主机要求 |
|---|---|---|---|---|
| macOS | macos_arm64、macos_x64(macos) |
.app + .dmg |
沙盒 .pkg |
签名与公证需 macOS |
| Windows | windows_x64、windows_arm64(windows) |
.exe 目录 + NSIS 安装程序 |
.msix |
任意平台(Go 交叉编译) |
| Linux | linux_x64、linux_arm64(linux) |
二进制目录 + .deb、Arch 包、.AppImage |
.tar.gz + AppStream + Flatpak 清单 |
任意平台(Go 交叉编译) |
| Web | web |
静态 WebAssembly 站点 + .zip |
同静态站点 | 任意平台 |
| iOS | ios、ios_simulator |
.ipa |
.ipa |
macOS + Xcode |
| Android | android_arm64(android)、android_x64 |
.apk |
.aab |
任意平台(android_x64 需 NDK) |
macOS
构建 Apple Silicon、Intel 或同时构建两者:
go tool nsgo build -target macos
- 代码签名:未设置签名身份时使用临时签名(ad hoc,仅适合本机测试,下载后会被 Gatekeeper 拦截)。直接分发请通过
sign.identity或-sign指定 Developer ID Application 证书:go tool nsgo build -target macos -sign "Developer ID Application: Example Studio (TEAMID)" - 公证(Notarization):为了让其他 Mac 无警告打开,请在
sign.notarize或-notarize <profile>指定通过xcrun notarytool store-credentials保存的钥匙串配置。在 CI 环境中,可改为设置 App Store Connect API 密钥环境变量:NSGO_NOTARY_KEY(.p8路径)、NSGO_NOTARY_KEY_ID和NSGO_NOTARY_ISSUER。nsgo build会自动提交.dmg(或打包的.app)、等待审核并将票据装订(staple)到.app和.dmg上。 - Mac App Store:设置
macos.category(例如public.app-category.games)、sign.macos_profile(Mac App Store 描述文件)以及可选的sign.installer(Mac Installer Distribution 证书),然后以-channel store构建:go tool nsgo build -channel store -target macosnsgo build会启用 App Sandbox 签名并生成可直接通过 Transporter 上传的.pkg安装包。
Windows
构建 x64、ARM64 或两者:
go tool nsgo build -target windows
- 直接分发:生成应用目录和 NSIS 安装程序(默认
-installers=true)。在nsgo.yaml中填写windows.publisher和copyright,用于填充可执行文件元数据和卸载项信息。 - 代码签名:为可执行文件和安装程序签名以避免 SmartScreen 拦截警告。通过
-certificate(或sign.certificate)指定 PKCS#12.pfx证书,用环境变量NSGO_CERTIFICATE_PASSWORD提供密码,并可设置 RFC 3161 时间戳服务器(-timestamp-url/sign.timestamp_url,默认为http://timestamp.digicert.com):
如果证书在硬件令牌或云签名服务中,请使用NSGO_CERTIFICATE_PASSWORD="$PFX_PASSWORD" \ go tool nsgo build -target windows -certificate certs/win.pfx-sign-command(或sign.sign_command),其中%1代表待签名文件路径。 - Microsoft Store:在
nsgo.yaml中填写 Partner Center 分配的windows.store.identity、windows.store.publisher(CN=...)和windows.store.publisher_name,再运行-channel store生成.msix包(包本身不签名,由商店发布时签名):go tool nsgo build -channel store -target windows
Linux
构建 x64、ARM64 或两者:
go tool nsgo build -target linux
- 直接分发:生成
.deb(Debian/Ubuntu)、Arch 软件包和.AppImage。在nsgo.yaml中配置桌面元数据:
若游戏附带了外部辅助程序,可通过linux: categories: [Game] maintainer: "Example Studio <games@example.com>" summary: "A 2D adventure game" license: MITlinux.depends和linux.recommends声明额外依赖。 - Flathub / Flatpak:使用
-channel store会生成包含<id>.metainfo.xmlAppStream 元数据的.tar.gz归档,以及面向 GNOME 运行时的flatpak/<id>.yml清单(可用linux.flatpak_runtime覆盖默认运行时版本)。可将清单提交到 Flathub,或本地用flatpak-builder构建。
Web
构建静态 WebAssembly 发布包:
go tool nsgo build -target web
部署前可直接在本地启动静态服务验证正式构建:
go tool nsgo build -target web -run
dist/<name>-<version>-web/ 中包含 HTML、JS、WebAssembly 二进制和 resources/ 文件,同时 releases 目录会生成一份 .zip 压缩包。将目录内容上传到任意静态托管服务(GitHub Pages、Cloudflare Pages、Netlify、itch.io 或 S3)即可上线。注意浏览器要求在首次用户手势之后才能播放音频(详见 sound)。
iOS
需要在安装了 Xcode 的 macOS 上构建。可构建真机 .ipa 或模拟器包:
go tool nsgo build -target ios
go tool nsgo build -target ios_simulator
- 签名:通过
sign.profile(或-profile)提供与id匹配的 App Store、Ad Hoc 或 Development 描述文件。nsgo build会自动从钥匙串选择匹配的签名证书,也可以用sign.identity(或-sign)显式指定。 - 商店提交注意事项:
- 使用 Apple 的 Transporter 应用或 Xcode 将
<name>.ipa上传至 App Store Connect / TestFlight。 - 每次上传都必须递增
build_number(CFBundleVersion)。 - 使用
apple.requires_full_screen和apple.orientations(portrait、portrait_upside_down、landscape_left、landscape_right)配置 iPad 分屏与屏幕方向,并在apple.info下添加所需的Info.plist字段。
- 使用 Apple 的 Transporter 应用或 Xcode 将
Android
构建 ARM64(只需要 Go,使用 CGO_ENABLED=0,无需 Android SDK 或 NDK):
go tool nsgo build -target android_arm64
如需同时构建 android_x64(用于 x86_64 模拟器或 Chromebook),请安装 Android NDK 后传入 -target android_arm64,android_x64。
- 签名:通过
sign.keystore(或-keystore)指定 PKCS#12 或 JKS 密钥库,通过sign.key_alias(或-key-alias)指定密钥别名。切勿把密码写入nsgo.yaml,请使用环境变量传递:
未配置密钥库时,NSGO_KEYSTORE_PASSWORD="$STORE_PW" NSGO_KEY_PASSWORD="$KEY_PW" \ go tool nsgo build -channel store -target android_arm64 \ -keystore certs/upload.p12 -key-alias uploadnsgo build会使用项目自带的调试密钥签名 APK(仅限侧载测试,无法上传 Google Play)。 - Google Play:使用
-channel store生成已签名的.aab(Android App Bundle)上传至 Google Play Console。每次上传需递增build_number(versionCode),按 Google Play 当前要求设置android.target_sdk(minSdkVersion为 28),并在android.permissions下声明额外权限。