macos-spm-app-packaging

macOS SwiftPM 应用打包（无需 Xcode）

概述

初始化完整的 SwiftPM macOS 应用文件夹，然后在不使用 Xcode 的情况下构建、打包并运行。使用 assets/templates/bootstrap/ 作为起始布局，并参阅 references/packaging.md + references/release.md 了解打包和发布详情。

两步工作流

1. 初始化项目文件夹

   • 将 assets/templates/bootstrap/ 复制到新仓库。
   • 重命名 Package.swift、Sources/MyApp/ 和 version.env 中的 MyApp。
   • 自定义 APP_NAME、BUNDLE_ID 和版本号。

2. 构建、打包并运行初始化后的应用

   • 将 assets/templates/ 中的脚本复制到仓库中（例如 Scripts/）。
   • 构建/测试：swift build 和 swift test。
   • 打包：Scripts/package_app.sh。
   • 运行：Scripts/compile_and_run.sh（推荐）或 Scripts/launch.sh。
   • 发布（可选）：Scripts/sign-and-notarize.sh 和 Scripts/make_appcast.sh。
   • 创建标签并发布到 GitHub（可选）：创建 git 标签，将 zip/appcast 上传到 GitHub 发布版本，然后发布。

端到端最小示例

从初始化到运行应用的最短路径：

# 1. Copy and rename the skeleton
cp -R assets/templates/bootstrap/ ~/Projects/MyApp
cd ~/Projects/MyApp
sed -i '' 's/MyApp/HelloApp/g' Package.swift version.env

# 2. Copy scripts
cp assets/templates/package_app.sh Scripts/
cp assets/templates/compile_and_run.sh Scripts/
chmod +x Scripts/*.sh

# 3. Build and launch
swift build
Scripts/compile_and_run.sh

验证检查点

在关键步骤后运行这些检查，以便在进入下一阶段前尽早发现问题。

打包后（Scripts/package_app.sh）：

# Confirm .app bundle structure is intact
ls -R build/HelloApp.app/Contents

# Check that the binary is present and executable
file build/HelloApp.app/Contents/MacOS/HelloApp

签名后（Scripts/sign-and-notarize.sh 或临时开发签名）：

# Inspect signature and entitlements
codesign -dv --verbose=4 build/HelloApp.app

# Verify the bundle passes Gatekeeper checks locally
spctl --assess --type execute --verbose build/HelloApp.app

公证并装订票据后：

# Confirm the staple ticket is attached
stapler validate build/HelloApp.app

# Re-run Gatekeeper to confirm notarization is recognised
spctl --assess --type execute --verbose build/HelloApp.app

常见公证失败

症状	可能原因	解决方法
The software asset has already been uploaded	同一版本重复提交	在 version.env 中递增 BUILD_NUMBER，然后重新打包。
Package Invalid: Invalid Code Signing Entitlements	.entitlements 文件中的权限与配置文件不匹配	对照 Apple 允许的集合检查权限；移除不受支持的键。
The executable does not have the hardened runtime enabled	codesign 调用中缺少 --options runtime 标志	编辑 sign-and-notarize.sh，为所有 codesign 调用添加 --options runtime。
公证卡住 / 未收到状态邮件	xcrun notarytool 网络或凭据问题	运行 xcrun notarytool history 检查状态；如果 App Store Connect API 密钥已过期，请重新导出。
公证成功后 stapler validate 失败	票据尚未传播	等待约 60 秒，然后重新运行 xcrun stapler staple。

模板

• assets/templates/package_app.sh：构建二进制文件、创建 .app 捆绑包、复制资源并签名。
• assets/templates/compile_and_run.sh：开发循环，用于终止正在运行的应用、打包并启动。
• assets/templates/build_icon.sh：从 Icon Composer 文件生成 .icns（需要安装 Xcode）。
• assets/templates/sign-and-notarize.sh：对发布版本进行公证、装订票据并压缩。
• assets/templates/make_appcast.sh：为更新生成 Sparkle appcast 条目。
• assets/templates/setup_dev_signing.sh：创建稳定的开发代码签名身份。
• assets/templates/launch.sh：用于启动已打包 .app 的简单启动器。
• assets/templates/version.env：打包脚本使用的版本文件示例。
• assets/templates/bootstrap/：精简的 SwiftPM macOS 应用骨架（Package.swift、Sources/、version.env）。

注意事项

• 明确配置权限和签名；请编辑模板脚本，而不是重新实现。
• 如果不使用 Sparkle 更新，请移除 Sparkle 相关步骤。
• Sparkle 依赖捆绑包的构建号（CFBundleVersion），因此每次更新都必须递增 version.env 中的 BUILD_NUMBER。
• 对于菜单栏应用，打包时设置 MENU_BAR_APP=1，以便在 Info.plist 中生成 LSUIElement。