guide-macos-spm-packaging

指南技能 — 这是一份专家工作流／模式指南，而非 API 参考文档。 最初来自 Thomas Ricouard 的 Dimillian/Skills。MIT 许可证。

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 s，然后重新运行 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。