Skip to main content

Mac App Store 提交指南

🌐 Mac App Store Submission Guide

本指南提供以下信息：

🌐 This guide provides information on:

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

要求​

🌐 Requirements

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

🌐 To sign Electron apps, the following tools must be installed first:

你还必须注册一个 Apple 开发者账户并加入 苹果开发者计划。

🌐 You also have to register an Apple Developer account and join the Apple Developer Program.

签署 Electron 应用​

🌐 Sign Electron apps

Electron 应用可以通过 Mac 应用商店或其他方式分发。每种方式都需要不同的签名和测试方法。本指南侧重于通过 Mac 应用商店分发。

🌐 Electron apps can be distributed through Mac App Store or outside it. Each way requires different ways of signing and testing. This guide focuses on distribution via Mac App Store.

以下步骤说明了如何从苹果获取证书、如何签署 Electron 应用以及如何测试它们。

🌐 The following steps describe how to get the certificates from Apple, how to sign Electron apps, and how to test them.

获得证书​

🌐 Get certificates

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

🌐 The simplest way to get signing certificates is to use Xcode:

  1. 打开 Xcode 并打开“账户”偏好设置；
  2. 使用你的 Apple 账户登录；
  3. 选择一个团队并点击“管理证书”；
  4. 在签名证书表的左下角，点击添加按钮（+），并添加以下证书：
    • 苹果开发
    • 苹果分销

“Apple Development” 证书用于在已在 Apple 开发者网站上注册的设备上对应用进行开发和测试。注册方法将在 准备配置描述文件 中描述。

🌐 The "Apple Development" certificate is used to sign apps for development and testing, on machines that have been registered on Apple Developer website. The method of registration will be described in Prepare provisioning profile.

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

🌐 Apps signed with the "Apple Development" certificate cannot be submitted to Mac App Store. For that purpose, apps must be signed with the "Apple Distribution" certificate instead. But note that apps signed with the "Apple Distribution" certificate cannot run directly, they must be re-signed by Apple to be able to run, which will only be possible after being downloaded from the Mac App Store.

其他证书​

🌐 Other certificates

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

🌐 You may notice that there are also other kinds of certificates.

“开发者 ID 证书”用于在将应用分发到 Mac App Store 之外之前对其进行签名。

🌐 The "Developer ID Application" certificate is used to sign apps before distributing them outside the Mac App Store.

“开发者 ID 安装程序”和“Mac 安装程序分发”证书用于签署 Mac 安装程序包，而不是应用本身。大多数 Electron 应用不使用 Mac 安装程序包，因此通常不需要这些证书。

🌐 The "Developer ID Installer" and "Mac Installer Distribution" certificates are used to sign the Mac Installer Package instead of the app itself. Most Electron apps do not use Mac Installer Package so they are generally not needed.

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

🌐 The full list of certificate types can be found here.

使用“Apple Development”和“Apple Distribution”证书签名的应用只能在 应用沙盒 下运行，因此它们必须使用 Electron 的 MAS 版本构建。然而，“Developer ID Application”证书没有此限制，因此使用该证书签名的应用可以使用普通版本或 MAS 版本的 Electron。

🌐 Apps signed with "Apple Development" and "Apple Distribution" certificates can only run under App Sandbox, so they must use the MAS build of Electron. However, the "Developer ID Application" certificate does not have this restriction, so apps signed with it can use either the normal build or the MAS build of Electron.

旧证书名称​

🌐 Legacy certificate names

多年来，苹果一直在更改证书的名称，你在阅读旧文档时可能会遇到它们，而且一些工具仍然使用其中一个旧名称。

🌐 Apple has been changing the names of certificates during past years, you might encounter them when reading old documentations, and some utilities are still using one of the old names.

  • “Apple 分发”证书也被命名为“第三方 Mac 开发者应用”和“Mac 应用分发”。
  • “Apple 开发”证书也被称为“Mac 开发者”和“开发”。

准备配置文件​

🌐 Prepare provisioning profile

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

🌐 If you want to test your app on your local machine before submitting your app to the Mac App Store, you have to sign the app with the "Apple Development" certificate with the provisioning profile embedded in the app bundle.

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

🌐 To create a provisioning profile, you can follow the below steps:

  1. 在 Apple Developer 网站上打开“证书、标识符与描述文件”页面。
  2. 在“标识符”页面为你的应用添加新的应用 ID。
  3. 在“设备”页面注册你的本地计算机。你可以在“系统信息”应用的“硬件”页面找到计算机的“设备 ID”。
  4. 在“配置文件”页面注册新的配置文件，并将其下载到 /path/to/yourapp.provisionprofile。

启用 Apple 的应用沙箱​

🌐 Enable Apple's App Sandbox

提交到 Mac 应用商店的应用必须在 Apple 的 应用沙盒 下运行，并且只有 Electron 的 MAS 版本才能在应用沙箱中运行。Electron 的标准 darwin 版本在应用沙箱下运行时将无法启动。

🌐 Apps submitted to the Mac App Store must run under Apple's App Sandbox, and only the MAS build of Electron can run with the App Sandbox. The standard darwin build of Electron will fail to launch when run under App Sandbox.

使用 @electron/osx-sign 签署应用时，它会自动将必要的权限添加到应用的权限中。

🌐 When signing the app with @electron/osx-sign, it will automatically add the necessary entitlements to your app's entitlements.

没有 electron-osx-sign 的额外步骤

如果你在不使用 @electron/osx-sign 的情况下签署应用，必须确保应用包的权限至少包含以下键：

🌐 If you are signing your app without using @electron/osx-sign, you must ensure the app bundle's entitlements have at least following keys:

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 开发者账户的团队 ID，your.bundle.id 应替换为应用的 App ID。

🌐 The TEAM_ID should be replaced with your Apple Developer account's Team ID, and the your.bundle.id should be replaced with the App ID of the app.

以下权限必须添加到应用包中的二进制文件和辅助程序中：

🌐 And the following entitlements must be added to the binaries and helpers in the app's bundle:

<?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 开发者账户的团队 ID：

🌐 And the app bundle's Info.plist must include ElectronTeamID key, which has your Apple Developer account's Team ID as its value:

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

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

签署应用以进行开发​

🌐 Sign apps for development

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

🌐 To sign an app that can run on your development machine, you must sign it with the "Apple Development" certificate and pass the provisioning profile to @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。

🌐 If you are signing without @electron/osx-sign, you must place the provisioning profile to YourApp.app/Contents/embedded.provisionprofile.

已签名的应用只能在由配置文件注册的机器上运行，这是提交到 Mac 应用商店之前测试已签名应用的唯一方法。

🌐 The signed app can only run on the machines that registered by the provisioning profile, and this is the only way to test the signed app before submitting to Mac App Store.

签署应用以提交到 Mac App Store​

🌐 Sign apps for submitting to the Mac App Store

要签署将提交到 Mac 应用商店的应用，你必须使用“Apple 分发”证书进行签署。请注意，使用此证书签署的应用除非从 Mac 应用商店下载，否则无法在其他地方运行。

🌐 To sign an app that will be submitted to Mac App Store, you must sign it with the "Apple Distribution" certificate. Note that apps signed with this certificate will not run anywhere, unless it is downloaded from Mac App Store.

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

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

将应用提交到 Mac App Store​

🌐 Submit apps to the Mac App Store

在使用“Apple Distribution”证书签署应用后，你可以继续将其提交到 Mac 应用商店。

🌐 After signing the app with the "Apple Distribution" certificate, you can continue to submit it to Mac App Store.

然而，本指南并不能保证你的应用会被苹果批准；你仍然需要阅读苹果关于如何满足 Mac 应用商店要求的 提交你的应用 指南。

🌐 However, this guide does not ensure your app will be approved by Apple; you still need to read Apple's Submitting Your App guide on how to meet the Mac App Store requirements.

上传​

🌐 Upload

应使用 苹果运输车 将已签名的应用上传到 App Store。上传前，请确保已连接 创建了记录 以进行处理。

如果你看到类似使用私有 API 的错误，你应该检查这个应用是否使用了 Electron 的 MAS 版本。

🌐 If you are seeing errors like private APIs uses, you should check if the app is using the MAS build of Electron.

提交审核​

🌐 Submit for review

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

🌐 After uploading, you should submit your app for review.

MAS 构建的局限性​

🌐 Limitations of MAS Build

为了满足应用沙箱的所有要求，MAS 版本中已禁用以下模块：

🌐 In order to satisfy all requirements for app sandboxing, the following modules have been disabled in the MAS build:

  • crashReporter
  • autoUpdater

并且以下行为已更改：

🌐 and the following behaviors have been changed:

  • 视频捕获可能不适用于某些机器。
  • 某些辅助功能可能无法使用。
  • 应用不会意识到 DNS 更改。

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

🌐 Also, due to the usage of app sandboxing, the resources which can be accessed by the app are strictly limited; you can read App Sandboxing for more information.

额外权利​

🌐 Additional entitlements

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

🌐 Every app running under the App Sandbox will run under a limited set of permissions, which limits potential damage from malicious code. Depending on which Electron APIs your app uses, you may need to add additional entitlements to your app's entitlements file. Otherwise, the App Sandbox may prevent you from using them.

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

🌐 Entitlements are specified using a file with format like property list (.plist) or XML. You must provide an entitlement file for the application bundle itself and a child entitlement file which basically describes an inheritance of properties, specified for all other enclosing executable files like binaries, frameworks (.framework), and dynamically linked libraries (.dylib).

完整的权限列表可在 应用沙盒 文档中查阅，但以下是你在 MAS 应用中可能需要的一些权限。

🌐 A full list of entitlements is available in the App Sandbox documentation, but below are a few entitlements you might need for your MAS app.

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

🌐 With @electron/osx-sign, you can set custom entitlements per file as such:

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)
  })
})

网络接入​

🌐 Network access

启用传出网络连接以允许你的应用连接到服务器：

🌐 Enable outgoing network connections to allow your app to connect to a server:

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

启用传入的网络连接，以允许你的应用打开网络监听套接字：

🌐 Enable incoming network connections to allow your app to open a network listening socket:

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

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

🌐 See the Enabling Network Access documentation for more details.

dialog.showOpenDialog​

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

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

🌐 See the Enabling User-Selected File Access documentation for more details.

dialog.showSaveDialog​

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

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

🌐 See the Enabling User-Selected File Access documentation for more details.

Electron 使用的密码算法​

🌐 Cryptographic Algorithms Used by Electron

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

🌐 Depending on the countries in which you are releasing your app, you may be required to provide information on the cryptographic algorithms used in your software. See the encryption export compliance docs for more information.

Electron 使用以下加密算法：

🌐 Electron uses following cryptographic algorithms: