跳到主要內容

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 開發）
    • 「Apple Distribution」（Apple 發布）

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

使用「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」憑證沒有此限制，因此使用它簽署的應用程式可以使用普通建置版本或 MAS 建置版本的 Electron。

舊版憑證名稱​

Apple 在過去幾年中一直在更改憑證的名稱，您在閱讀舊文件時可能會遇到它們，並且某些實用工具仍然使用舊名稱之一。

  • 「Apple Distribution」憑證也曾被命名為「3rd Party Mac Developer Application」和「Mac App Distribution」。
  • 「Apple Development」憑證也曾被命名為「Mac Developer」和「Development」。

準備佈建描述檔​

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

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

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

啟用 Apple 的 App Sandbox​

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

使用 @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 應替換為應用程式的 App 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/>

啟用內送網路連線以允許您的應用程式開啟網路監聽通訊端

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