---

name: macos-spm-app-packaging description: 无需 Xcode 项目即可搭建、构建、签名和打包 SwiftPM macOS 应用。 risk: safe source: "Dimillian/Skills (MIT)" date_added: "2026-03-25"

macOS SwiftPM 应用打包（无需 Xcode）

概述

引导一个完整的 SwiftPM macOS 应用文件夹，然后在不使用 Xcode 的情况下构建、打包和运行它。使用 assets/templates/bootstrap/ 作为起始布局，使用 references/packaging.md + references/release.md 获取打包和发布详情。

何时使用

• 当用户需要一个基于 SwiftPM 的 macOS 应用而不依赖 Xcode 项目时。
• 当你需要 SwiftPM 应用的打包、签名、公证或 appcast 指导时。

两步工作流程

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。

限制

• 仅在任务明确匹配上述描述的范围时使用此技能。