跳至主要內容

Mac App Store 提交指南

本指南提供以下資訊：

  • 如何在 macOS 上簽署 Electron 應用程式；
  • 如何將 Electron 應用程式提交至 Mac App Store (MAS)；
  • MAS 建置的限制。

需求​

若要簽署 Electron 應用程式，必須先安裝以下工具：

您還必須註冊 Apple 開發者帳號並加入 Apple 開發者計畫。

簽署 Electron 應用程式​

Electron 應用程式可透過 Mac App Store 或在外部發佈。每種方式都需要不同的簽署和測試方法。本指南著重於透過 Mac App Store 發佈。

以下步驟說明如何從 Apple 取得憑證、如何簽署 Electron 應用程式以及如何測試它們。

取得憑證​

取得簽署憑證最簡單的方法是使用 Xcode

  1. 開啟 Xcode 並開啟「帳號」偏好設定；
  2. 使用您的 Apple 帳號登入；
  3. 選取一個團隊並按一下「管理憑證」；
  4. 在簽署憑證表的左下角，按一下「新增」按鈕 (+)，並新增以下憑證：
    • 「Apple Development」
    • 「Apple Distribution」

「Apple Development」憑證用於簽署在 Apple 開發者網站上註冊的機器上開發和測試的應用程式。註冊方法將在準備佈建描述檔中說明。

使用「Apple Development」憑證簽署的應用程式無法提交至 Mac App Store。為此，應用程式必須改用「Apple Distribution」憑證簽署。但請注意，使用「Apple Distribution」憑證簽署的應用程式無法直接執行，它們必須由 Apple 重新簽署才能執行，這只有在從 Mac App Store 下載後才有可能。

其他憑證​

您可能會注意到還有其他類型的憑證。

「開發者 ID 應用程式」憑證用於在 Mac App Store 外部發佈應用程式之前簽署它們。

「開發者 ID 安裝程式」和「Mac 安裝程式發佈」憑證用於簽署 Mac 安裝程式套件，而不是應用程式本身。大多數 Electron 應用程式不使用 Mac 安裝程式套件，因此通常不需要它們。

憑證類型的完整清單可以在此處找到。

使用「Apple Development」和「Apple Distribution」憑證簽署的應用程式只能在 App Sandbox 下執行，因此它們必須使用 Electron 的 MAS 建置。但是，「開發者 ID 應用程式」憑證沒有此限制，因此使用它簽署的應用程式可以使用 Electron 的一般建置或 MAS 建置。

舊版憑證名稱​

Apple 在過去幾年中一直在變更憑證的名稱，您在閱讀舊文件時可能會遇到它們，而且某些公用程式仍然使用其中一個舊名稱。

  • 「Apple Distribution」憑證也稱為「第三方 Mac 開發者應用程式」和「Mac App Distribution」。
  • 「Apple Development」憑證也稱為「Mac 開發者」和「開發」。

準備佈建描述檔​

如果您想在將應用程式提交至 Mac App Store 之前在您的本機上測試應用程式，則必須使用「Apple Development」憑證簽署應用程式，並將佈建描述檔內嵌在應用程式套件中。

若要建立佈建描述檔，您可以按照以下步驟操作：

  1. 在 Apple 開發者網站上開啟「憑證、識別碼和描述檔」頁面。
  2. 在「識別碼」頁面中為您的應用程式新增一個新的應用程式 ID。
  3. 在「裝置」頁面中註冊您的本機。您可以在「系統資訊」應用程式的「硬體」頁面中找到您機器的「裝置 ID」。
  4. 在「描述檔」頁面中註冊新的佈建描述檔，並將其下載到 /path/to/yourapp.provisionprofile。

啟用 Apple 的 App Sandbox​

提交至 Mac App Store 的應用程式必須在 Apple 的 App Sandbox 下執行，而且只有 Electron 的 MAS 建置才能在 App Sandbox 下執行。當在 App Sandbox 下執行時，Electron 的標準 darwin 建置將無法啟動。

當使用 @electron/osx-sign 簽署應用程式時，它會自動將必要的權限新增至您應用程式的權限中。

沒有 electron-osx-sign 的額外步驟

如果您未使用 @electron/osx-sign 簽署應用程式，則必須確保應用程式套件的權限至少具有以下金鑰：

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 應取代為應用程式的應用程式 ID。

而且必須將以下權限新增至應用程式套件中的二進位檔和輔助程式：

<?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

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

當使用 @electron/osx-sign 時，ElectronTeamID 金鑰會透過從憑證名稱中擷取團隊 ID 來自動新增。如果 @electron/osx-sign 無法找到正確的團隊 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 進行處理，請確保您在上傳之前建立了記錄。

如果您看到諸如使用私有 API 之類的錯誤，則應檢查應用程式是否正在使用 Electron 的 MAS 建置。

提交以供審查​

上傳後，您應該提交您的應用程式以供審查。

MAS 建置的限制​

為了滿足應用程式沙箱的所有要求，MAS 建置中已停用以下模組：

  • crashReporter
  • autoUpdater

而且以下行為已變更：

  • 對於某些機器，視訊擷取可能無法運作。
  • 某些輔助功能可能無法運作。
  • 應用程式將不會知道 DNS 變更。

此外，由於使用了應用程式沙箱，應用程式可以存取的資源受到嚴格限制；您可以閱讀 App Sandboxing 以取得更多資訊。

其他權限​

在 App Sandbox 下執行的每個應用程式都將在有限的權限集下執行，這限制了惡意程式碼的潛在損害。根據您的應用程式使用的 Electron API，您可能需要在應用程式的權限檔案中新增其他權限。否則，App Sandbox 可能會阻止您使用它們。

權限設定是使用類似屬性列表（.plist）或 XML 格式的檔案來指定的。您必須為應用程式套件本身提供一個權限檔案，以及一個子權限檔案，該檔案基本上描述了屬性的繼承關係，並指定給所有其他封閉的可執行檔案，例如二進制檔案、框架（.framework）和動態連結程式庫（.dylib）。

完整的權限列表可在App Sandbox 文件中找到，但以下是您可能需要為 MAS 應用程式設定的一些權限。

使用 @electron/osx-sign，您可以像這樣為每個檔案設定自訂權限

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/>

啟用對內網路連線，以允許您的應用程式開啟網路監聽 Socket

<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 使用以下加密演算法