什么是 swift-export?

swift-export 是一个命令行工具，用于为 macOS 生成签名和公证的安装程序包。生成的安装程序包可以包含任何可执行文件（从 Swift Package Manager 项目构建）和可选的有效负载，例如 LaunchDaemons plist 文件。它在 macOS 13 及以上版本上运行。

您可以从这里下载安装程序：swift-export.pkg，或者从源代码构建该工具。

基本用法

从 Swift 包构建通用二进制文件
对其进行签名
生成签名并公证的安装程序包

命令行选项

假设工作目录是包含 Package.swift 文件的目录

swift export --identifier <identifier> --executable-certificate <application cert> --package-certificate <installer cert> --package-version <version> --notary-profile <notary profile name>

identifier：可执行文件的唯一标识符，通常采用 com.your-domain.executable-name 的形式
application cert 和 installer cert：用于代码签名的证书（请参阅下面的代码签名身份）
version：安装程序包的版本
notary profile name：存储在钥匙串中用于公证的配置文件的名称（请参阅下面的公证身份）

配置文件和环境

如果项目包含一个名为 "export.yml" 的文件，该文件位于其根目录或名为 "export" 的目录中，内容如下

executable:
  identifier: com.your-domain.executable-name
package:
  version: 1.0

并且定义了以下环境变量

SWIFT_EXPORT_EXECUTABLE_CERTIFICATE=<application cert>
SWIFT_EXPORT_PACKAGE_CERTIFICATE=<installer cert>
SWIFT_EXPORT_NOTARY_PROFILE=<notary profile name>

那么该命令可以简化为 swift export。

高级用法

沙盒化和授权

默认情况下，可执行文件在启用硬化运行时的情况下构建，而无需沙盒化。对于其他情况（例如，启用沙盒或授予其他授权），可以提供授权文件。它应命名为 "hardened.entitlements"，并位于与 export.yml 文件相同的目录中，或者可以在配置文件中指定其路径。

安装目标位置

默认情况下，可执行文件安装在 /usr/local/bin 中。可以通过将以下条目添加到 export.yml 文件来更改此设置

package:
  executable:
    destination: /path/to/install/directory

其他安装程序有效负载

可以提供其他文件作为安装程序包的一部分。例如，如果可执行文件是守护程序，则应将 plist 文件（例如 com.your-domain.service-name.plist）安装在 /Library/LaunchDaemons 中

将 com.your-domain.service-name.plist 文件添加到您的项目
将以下行添加到 export.yml

package:
  resources:
  - source: com.your-domain.service-name.plist
    destination: /Library/LaunchDaemons

选项优先级

某些设置可以作为命令行选项给出，并在配置文件中或作为环境变量定义。在这种情况下，命令行选项的优先级高于配置文件设置，配置文件设置的优先级高于环境变量。

以下元素是强制性的，无论它们是以环境变量、配置文件还是在命令行中提供

可执行文件标识符
可执行文件证书
程序包证书
程序包版本
公证配置文件

其他一切都是可选的。

命令行选项

`--config-dir <path>`

指定包含配置和代码签名文件的目录。该路径可以是绝对路径，也可以是相对于当前目录的路径。

默认情况下，如果在当前目录中找到名为 export 的目录，则使用该目录；否则，使用当前目录。

`--export-config <path>`

包含导出配置的 export.yaml、export.yml 或 export.plist 文件的路径。该路径可以是绝对路径，也可以是相对于 --config-dir 指定的目录的路径。

默认情况下，将按此顺序搜索文件 export.yaml、export.yml 和 export.plist。

`--identifier <identifier>`

用于对可执行二进制文件进行签名的标识符。格式与捆绑包标识符相同，例如“com.example.MyAwesomeTool”。

此选项会覆盖导出配置中 executable.identifier 中指定的标识符。

`--executable-certificate <identity>`

用于对可执行文件进行签名的“Developer ID Application”证书。可以提供证书的公用名称或 SHA-1 哈希。

此选项会覆盖 SWIFT_EXPORT_EXECUTABLE_CERTIFICATE 环境变量和导出配置中 executable.certificate 中指定的值。

`--package-certificate <identity>`

用于对安装程序包进行签名的“Developer ID Installer”证书。可以提供证书的公用名称或 SHA-1 哈希。

此选项会覆盖 SWIFT_EXPORT_PACKAGE_CERTIFICATE 环境变量和导出配置中 package.certificate 中指定的值。

`--entitlements <path>`

用于代码签名的授权文件的路径。该路径可以是绝对路径，也可以是相对于包含导出配置文件的目录的路径。

此选项会覆盖导出配置中 executable.entitlements 中指定的路径。

默认值：如果此文件存在，则为 hardened.entitlements。否则，将提供默认授权，启用硬化运行时并禁用沙盒。

`--output <path>`

输出路径（pkg 文件或父目录）。该路径可以是绝对路径，也可以是相对于当前目录的路径。

如果提供了目录，则包的名称将基于项目名称。

默认值：当前目录。

`--package-identifier <identifier>`

用于对安装程序包进行签名的标识符。格式与捆绑包标识符相同，例如“com.example.MyAwesomeTool”。

此选项会覆盖导出配置中 package.identifier 中指定的标识符。

默认值：与可执行文件标识符相同。

`--package-version <version>`

安装程序包的版本号。

此选项会覆盖导出配置中 package.version 中指定的标识符。

`--notary-profile <name>`

用于在提交程序包以进行公证时识别开发者帐户的钥匙串配置文件名称。

此选项会覆盖 SWIFT_EXPORT_NOTARY_PROFILE 环境变量和导出配置中 notary.profile 中指定的名称。

`--verbose`

打印调试和进度消息。

`--dry-run`

打印要执行的命令，而不实际执行它们。

`--help`

显示帮助信息。

配置文件

配置文件可以是 YAML 格式或 plist 格式。

如果使用 --export-config 选项指定了显式文件名，则使用该文件名。否则，swift export 会在 --config-dir 选项指定的目录中搜索名为 "export.yaml"、"export.yml" 或 "export.plist" 的文件。

如果既未给出 --export-config 选项也未给出 --config-dir 选项，则会在 "export" 目录（如果存在）中搜索配置文件，然后在当前目录中搜索配置文件。

配置文件具有以下结构（所有字段都是可选的）

executable
- architectures：目标架构列表，作为字符串数组，默认值：[arm64, x86_64]
- identifier：用于代码签名的唯一标识符
- certificate：Developer ID Application 证书名称或哈希
- entitlements：授权文件的路径（如果配置文件目录中存在此类文件，则默认为 "hardened.entitlements"，否则，可执行文件在启用硬化运行时和禁用沙盒的情况下构建）
package
- identifer：用于代码签名的唯一标识符（默认值：与 executable.identifier 相同）
- version：.pkg 文件的版本
- certificate：Developer ID Installer 证书名称或哈希
- executable
  - source：要构建的可执行文件的名称（默认值：由 Package.swift 确定）
  - destination：应安装可执行文件的路径（默认值：/usr/local/bin）
- resources：要安装的其他文件数组；对于每个文件
  - source：要复制到安装程序包的资源的名称或路径
  - destination：应安装资源的路径
notary
- keychain-profile：钥匙串中保存的凭据的名称（请参阅公证身份）

环境

某些设置不应出现在 git 存储库中，无论是出于安全原因，还是因为它们可能因用户而异。因此，这些设置可以作为环境变量提供

SWIFT_EXPORT_EXECUTABLE_CERTIFICATE：“Developer ID Application”证书的公用名称或 SHA-1 哈希
SWIFT_EXPORT_PACKAGE_CERTIFICATE：“Developer ID Installer”证书的公用名称或 SHA-1 哈希
SWIFT_EXPORT_NOTARY_PROFILE：用于公证的钥匙串配置文件的名称

由于这些设置对于给定用户很可能跨项目共享，因此建议在 shell 配置文件（~/.profile、~/.zshrc 等）中声明它们。

export SWIFT_EXPORT_EXECUTABLE_CERTIFICATE=...
export SWIFT_EXPORT_PACKAGE_CERTIFICATE=...
export SWIFT_EXPORT_NOTARY_PROFILE=...

代码签名身份

swift export 需要两个证书：用于对可执行文件进行签名的“Developer ID Application”证书，以及用于对安装程序包进行签名的“Developer ID Installer”证书。

可以在您的 Apple Developer 帐户上创建这些证书：https://developer.apple.com/account/resources/certificates/add

稍后可以通过它们的公用名称（通常为“Developer ID Application: your name (team id)”和“Developer ID Installer: your name (team id)”）或通过它们的 SHA-1 哈希（在钥匙串应用程序中证书的“详细信息”部分的底部可见）来引用这些证书。

注意

按公用名称搜索区分大小写
SHA-1 哈希必须恰好由 40 个十六进制数字组成（无空格）

公证身份

为了提交您的程序包以进行公证，您需要向公证服务提供您的开发者帐户的 Apple ID。实现此目的的安全方法是创建特定于应用程序的密码并将其存储在钥匙串中。

首先，按照以下说明在 https://appleid.apple.com 上生成特定于应用程序的密码：https://support.apple.com/en-us/102654

然后运行此命令：xcrun notarytool store-credentials。该工具将交互式提示您输入配置文件名称、您的开发者 Apple ID、特定于应用程序的密码以及您的团队 ID。

您的凭据存储在钥匙串中，现在您可以在需要提交任何应用程序或程序包以进行公证时向 notarytool 提供配置文件名称。