跳转到主要内容

Mac App Store 提交指南

本指南提供有关以下信息：

  • 如何在 macOS 上为 Electron 应用签名；
  • 如何将 Electron 应用提交到 Mac App Store (MAS)；
  • MAS 构建的限制。

要求​

要为 Electron 应用签名，必须先安装以下工具：

您还必须注册一个 Apple 开发者账户并加入 Apple Developer Program。

为 Electron 应用签名​

Electron 应用可以通过 Mac App Store 或其外部进行分发。每种方式都需要不同的签名和测试方法。本指南侧重于通过 Mac App Store 分发。

以下步骤将介绍如何从 Apple 获取证书、如何为 Electron 应用签名以及如何进行测试。

获取证书​

获取签名证书最简单的方法是使用 Xcode。

  1. 打开 Xcode 并打开“Accounts”偏好设置；
  2. 使用您的 Apple 账户登录；
  3. 选择一个团队，然后点击“Manage Certificates”（管理证书）；
  4. 在签名证书窗口的左下角，点击“Add”（添加）按钮 (+)，然后添加以下证书：
    • “Apple Development”（Apple 开发）
    • “Apple Distribution”（Apple 分发）

“Apple Development”证书用于在已在 Apple Developer 网站上注册的计算机上进行开发和测试签名应用。注册方法将在 准备配置文件 中介绍。

使用“Apple Development”证书签名的应用无法提交到 Mac App Store。为此，必须使用“Apple Distribution”证书进行签名。但请注意，使用“Apple Distribution”证书签名的应用无法直接运行，必须由 Apple 重新签名才能运行，这仅在从 Mac App Store 下载后才可能实现。

其他证书​

您可能会注意到还有其他类型的证书。

“Developer ID Application”（开发者 ID 应用程序）证书用于在 Mac App Store 外部分发应用之前进行签名。

“Developer ID Installer”（开发者 ID 安装程序）和“Mac Installer Distribution”（Mac 安装程序分发）证书用于对 Mac 安装程序包（而不是应用本身）进行签名。大多数 Electron 应用不使用 Mac 安装程序包，因此通常不需要它们。

证书类型的完整列表可以在 这里 找到。

使用“Apple Development”和“Apple Distribution”证书签名的应用只能在 App Sandbox 下运行，因此必须使用 Electron 的 MAS 构建。但是，“Developer ID Application”证书没有此限制，因此使用它签名的应用可以使用 Electron 的常规构建或 MAS 构建。

旧证书名称​

Apple 在过去几年中一直在更改证书名称，您在阅读旧文档时可能会遇到它们，并且某些实用工具仍在使用旧名称之一。

  • “Apple Distribution”证书也曾被称为“3rd Party Mac Developer Application”和“Mac App Distribution”。
  • “Apple Development”证书也曾被称为“Mac Developer”和“Development”。

准备配置文件​

如果您想在将应用提交到 Mac App Store 之前在本地计算机上进行测试，您必须使用带有嵌入在应用包中的配置文件的“Apple Development”证书对应用进行签名。

要 创建配置文件，您可以按照以下步骤操作：

  1. 在 Apple Developer 网站上打开“Certificates, Identifiers & Profiles”（证书、标识符和配置文件）页面。
  2. 在“Identifiers”（标识符）页面为您的应用添加新的 App ID。
  3. 在“Devices”（设备）页面注册您的本地计算机。您可以在“System Information”（系统信息）应用程序的“Hardware”（硬件）页面找到您计算机的“Device ID”（设备 ID）。
  4. 在“Profiles”（配置文件）页面注册新的 Provisioning Profile，并将其下载到 /path/to/yourapp.provisionprofile。

启用 Apple 的 App Sandbox​

提交到 Mac App Store 的应用必须在 Apple 的 App Sandbox 下运行，并且只有 Electron 的 MAS 构建才能与 App Sandbox 一起运行。Electron 的标准 darwin 构建在 App Sandbox 下运行时将无法启动。

在使用 @electron/osx-sign 对应用进行签名时，它会自动将必要的权限添加到应用的 entitlements 中。

不使用 electron-osx-sign 的额外步骤

如果您在不使用 @electron/osx-sign 的情况下对应用进行签名，则必须确保应用包的 entitlements 至少包含以下键：

entitlements.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.application-groups</key>
    <array>
      <string>TEAM_ID.your.bundle.id</string>
    </array>
  </dict>
</plist>

TEAM_ID 应替换为您 Apple Developer 账户的 Team ID，your.bundle.id 应替换为应用的 App ID。

并且必须将以下 entitlements 添加到应用包中的二进制文件和助手程序中：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.inherit</key>
    <true/>
  </dict>
</plist>

并且应用包的 Info.plist 必须包含 ElectronTeamID 键，其值为您的 Apple Developer 账户的 Team ID。

<plist version="1.0">
<dict>
  ...
  <key>ElectronTeamID</key>
  <string>TEAM_ID</string>
</dict>
</plist>

在使用 @electron/osx-sign 时，ElectronTeamID 键将通过从证书名称中提取 Team ID 来自动添加。如果 @electron/osx-sign 无法找到正确的 Team ID，您可能需要手动添加此键。

为开发签名应用​

要对可以在开发计算机上运行的应用进行签名，您必须使用“Apple Development”证书对其进行签名，并将配置文件传递给 @electron/osx-sign。

const { signAsync } = require('@electron/osx-sign')

signAsync({
  app: '/path/to/your.app',
  identity: 'Apple Development',
  provisioningProfile: '/path/to/your.provisionprofile'
})

如果您在不使用 @electron/osx-sign 的情况下进行签名，您必须将配置文件放置在 YourApp.app/Contents/embedded.provisionprofile。

签名后的应用只能在配置文件注册的计算机上运行，这是在提交到 Mac App Store 之前测试签名应用的唯一方法。

为提交到 Mac App Store 的应用签名​

要对将要提交到 Mac App Store 的应用进行签名，您必须使用“Apple Distribution”证书对其进行签名。请注意，使用此证书签名的应用将无法在任何地方运行，除非它从 Mac App Store 下载。

const { signAsync } = require('@electron/osx-sign')

signAsync({
  app: 'path/to/your.app',
  identity: 'Apple Distribution'
})

将应用提交到 Mac App Store​

使用“Apple Distribution”证书签名应用后，您可以继续将其提交到 Mac App Store。

但是，本指南不能保证您的应用会获得 Apple 的批准；您仍需要阅读 Apple 的 提交您的应用 指南，了解如何满足 Mac App Store 的要求。

上传​

应使用 Apple Transporter 将签名后的应用上传到 App Store Connect 进行处理，确保您在上传之前 创建了记录。

如果您看到“private APIs uses”（使用了私有 API）等错误，您应该检查应用是否使用了 Electron 的 MAS 构建。

提交审核​

上传后，您应该 提交您的应用以供审核。

MAS 构建的限制​

为了满足应用沙盒的所有要求，以下模块在 MAS 构建中已被禁用：

  • crashReporter
  • autoUpdater

以下行为已更改：

  • 某些机器上的视频捕获可能无法工作。
  • 某些辅助功能可能无法工作。
  • 应用将无法感知 DNS 更改。

此外，由于使用了应用沙盒，应用可以访问的资源受到严格限制；您可以阅读 App Sandboxing 以获取更多信息。

附加 entitlements​

在 App Sandbox 下运行的每个应用都将在有限的权限集下运行，这限制了恶意代码造成的潜在损害。根据您的应用使用了哪些 Electron API，您可能需要为应用的 entitlements 文件添加额外的 entitlements。否则，App Sandbox 可能会阻止您使用它们。

Entitlements 使用属性列表（.plist）或 XML 格式的文件进行指定。您必须为应用程序包本身提供一个 entitlement 文件，以及一个子 entitlement 文件，该文件基本上描述了所有其他包含的可执行文件（如二进制文件、框架（.framework）和动态链接库（.dylib））的属性继承。

在 App Sandbox 文档中可以找到 entitlements 的完整列表，但以下是一些您可能为 MAS 应用需要的 entitlements：

使用 @electron/osx-sign，您可以为每个文件设置自定义 entitlements，如下所示：

const { signAsync } = require('@electron/osx-sign')

function getEntitlementsForFile (filePath) {
  if (filePath.startsWith('my-path-1')) {
    return './my-path-1.plist'
  } else {
    return './alternate.plist'
  }
}

signAsync({
  optionsForFile: (filePath) => ({
    // Ensure you return the right entitlements path here based on the file being signed.
    entitlements: getEntitlementsForFile(filePath)
  })
})

网络访问​

启用出站网络连接，允许您的应用连接到服务器。

<key>com.apple.security.network.client</key>
<true/>

启用入站网络连接，允许您的应用打开网络监听套接字。

<key>com.apple.security.network.server</key>
<true/>

有关更多详细信息，请参阅 启用网络访问 文档。

dialog.showOpenDialog​

<key>com.apple.security.files.user-selected.read-only</key>
<true/>

有关更多详细信息，请参阅 启用用户选择文件访问 文档。

dialog.showSaveDialog​

<key>com.apple.security.files.user-selected.read-write</key>
<true/>

有关更多详细信息，请参阅 启用用户选择文件访问 文档。

Electron 使用的加密算法​

根据您发布应用的国家/地区，您可能需要提供有关您的软件使用的加密算法的信息。有关更多信息，请参阅 加密出口合规性文档。

Electron 使用以下加密算法：