前言：近期正在开发一个electron应用，并尝试打包上架mac的appstore中，此文记录中间的各种坑点。

基本概况

• 应用基于vue + electron，并将其升级至electron 25.3.0
• 打包使用electron-builder，并通过vue.config.js进行配置
• 应用直接打包成dmg并安装是正常运行的，但是为了上架应用商店，我在使用mas模式打包后遇到了各种各样的问题，本文即对此进行一些记录
• 上传之前的一些准备工作可以查阅electron官方文档：Mac App Store 应用程序提交指南
• 下文会反复提到，我们会将应用打包为mas包和mas-dev包。这里的“xxx包”指的是electron-builder配置项中mac-target后面的字段是mas还是mas-dev，这里也可以是zip、dmg等，想打什么包就用target来指定。通常，如果你只是想打包一个安装包给别人用而不上架App Store的话，那就直接打pkg或者dmg即可，这两种包应该是比较简单的，不在本文的讨论范围。本文是为了让你的app提交到App Store，因此本文会主要讨论mas和mas-dev。
• 重要：我们在提交apple审核的包是mas包，这个包在本地是无法运行的，必须提交到app store给苹果签名后，通过Testflight或是App Store下载后才能运行。而mas-dev包是只能运行在我们开发者本地的包（这个安装包给别人是无法运行的），这个包是最接近上架后的应用的情况，他专门用于检查mas包是否正常。
• mas包上传给苹果需要一个叫Transporter的app，前往appstore下载即可。如果mas-dev包能正常运行不报系统级的错（比如签名错误等），mas包也能通过Transpoter上传，那么你的签名是正确的，此时就可以提交给苹果审核。

第一步：准备工作

首先要在apple developer account中做一些设置

apple开发者中心.png

1. 证书certificate

这里你需要新建3个证书用于后续的开发。
首先打开你电脑里的钥匙串应用并创建一个钥匙串请求。这个文件后面要用到多次，请放到桌面上备用：

钥匙串.png

然后回到证书的页面上，点击新建，这里一次只能建一个证书，你需要分3次选择下面的3项：

• 你需要Mac Development证书来打出mas-dev包用于本地检查
• 你需要Apple Distribution证书来打出mas包用于提交审核，这种包可以提交到Testflight进行真机测试
• 你需要Developer ID Application证书来打普通dmg包，用于非mas包的测试

接下来根据页面的提示上传刚才的请求文件，苹果就会生成对应的证书，请把它们下载下来。

三个证书下载好之后双击安装，然后你就可以到钥匙串中看到他们（如果不知道这些证都干嘛用的，干脆都建一个以免后续麻烦）

证书安装

2. Identifier（类似app的身份证）

前往Identifier页面，你需要为你需要上架的应用指定一个id，这样苹果才能唯一标记你的应用。
这个id通常是url反过来写，比如“com.yourapp.yourname”

Identifier

3. 登记你的开发机

前往Devices页面，你必须添加你的开发用的电脑才能进行本地开发，因此需要添加自己的mac电脑到这里。

• 获取你电脑的id：系统设置-通用-系统报告，就可以看到你的UUID和UDID

  
  
  开发机登记
• 然后前往developer页面中添加你的设备

重要！如果你使用apple silicon（m1、m2）的机器，在添加设备时，需要将你电脑的UUID和UDID分两次，添加到网页里的设备列表中，即使苹果在网页上提示只需要UUID。如果缺了，那后面的profile很可能将无法安装到你电脑中导致mas-dev包无法运行。我的mac studio就是m2的，所以这里必须添加两次，把UUID和UDID都登记进去

3.jpg

4. 一些顶级证书的安装

打开 Apple PKI，下载以下的证书并安装

一些顶级证书的安装

5. 创建provisioning profile

创建provisioning profile

6. xcode中几个操作要做

• 去app store中下载最新的xcode，进入设置，点击Accounts，登录你的账号，点击右下角download Manual Profiles。每次在apple developer中新增provisioning profile都要到这里来点击一下这个按钮，否则你的Transporter将无法上传应用到Mac App Store

• 点击Manage Certificates，检查里面的证书是否和第一步certificate里面的显示的一致，并且都显示正常，是否提示缺少priviate key之类的，确保里面有Mac Developent和Mac App Distribution证书。没有的话回到第一步检查。

  
  
  xcode

第二步：项目的根目录下添加几个关键文件来指明你需要的沙盒权限

当你的应用提交到App Store后，审核人员会一一检查你应用的权限。本质上，他们是在检查你打完的包中的info.plist。这个文件是electron在打包时，从多个文件中合并出来的，下文会一一提到。

1. entitlements.mas.plist
   这个文件放置到项目的根目录下。这里记录了应用所需要的权限，这里的权限最终会被合并到应用的info.plist文件中，在后续的AppStore审核流程中，苹果审核人员会对这个文件提出的各种意见，所以你需要仔细检查这个文件里面的内容。
   在这个文件中（下面有示例，仔细看注释），除了sandbox、application-groups等必填项，还必须添加你的应用的自定义权限。详细列表见沙盒应用

• 这里的“自定义的权限”是指你的应用要用到的额外权限，比如是否允许网络连接、是否使用文件读取权限等。需要留意的是，不能一口气把所有权限全都无脑写上去，因为苹果的要求是，你在里面所写的权限，必须和你的应用完全相关，且无多余项，一个不能多一个不能少。苹果会一条一条审核你写的每一个权限是否被使用到、如何使用到的，如果审核人员没有测到则会被打回，并要求你回复他使用该权限的原因，有时候可能会要求你提供操作的视频录像，且录像中要包括该权限的申请画面。

• 另外，在某些权限（比如摄像头）的申请时，用户会收到弹框，这类弹框通常会有一个说明字段。比如申请摄像头权限时，用户会收到这样的弹框，其中下方那行说明权限用途的小字也是可以自定义的：

  
  
  授权弹框.png

• 但是这里有个坑点：由于打包后info.plist中的内容并非全部来自entitlements.mas.plist文件，他还包含来自electron-builder下config中extendInfo下的项目。
  举个例子，我们的应用需要摄像头权限，那么首先需要在entitlements.mas.plist中添加<key>com.apple.security.device.camera</key><true/>来表明app需要摄像头权限，然后还要在vue.config.js中，找到extendInfo中electronBuilder.builderOptions.mac.extendInfo，在下面添加NSCameraUsageDescription来标明申请权限的原因（就是权限弹框里给用户看的那行小字）。其他类似权限同理，比如麦克风等权限，都需要在这两个地方分别添加内容。

//electron-builder config
mac:{
  extendInfo:{
    "NSCameraUsageDescription": "In order to be able to connect to the OBS virtual camera correctly",
  }
}

完整的entitlements.mas.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> //要提交到mas必须有sandbox权限
    <true/>
    <key>com.apple.security.application-groups</key>
    <array>
      <string>XXXXXXX.com.appname.username</string>  //你的teamId.你应用的bundleId
    </array>
    <key>com.apple.application-identifier</key>
    <string>XXXXXXX.com.appname.username</string>  //你的teamId.你应用的bundleId
    <key>com.apple.security.cs.allow-jit</key> //electron20+必须有此项否则闪退
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key> //防闪退
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key> //防闪退
    <true/>
    //此项以下开始为自定义的权限，根据你的应用情况按需添加，不能多不能少
    <key>com.apple.security.files.user-selected.read-only</key> //如果electron有showOpenDialog则必须有此项
    <true/>
    <key>com.apple.security.files.user-selected.read-write</key> //如果electron有showSaveDialog则必须有此项
    <true/>
    <key>com.apple.security.files.downloads.read-write</key>
    <true/>
  </dict>
</plist>

2. entitlements.mas.inherit.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.inherit</key>
    <true/>
  </dict>
</plist>

3. entitlements.mas.loginhelper.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/>
    </dict>
</plist>

4. 两个provisionprofile预设
   前文提过，在打出mas-dev和mas包的时候，配置中就需要两个provisionprofile。一个development.provisionprofile用于打出mas-dev包（这个包用于本地检查）；一个distribution.provisionprofile用于打出mas包（用于提交mas上架）这两个文件已经在前文中去developer网站创建的provisioning profile，并下载好了，我们把它们放到了项目根目录下。

第三步：以mas和mas-dev模式打包你的应用，准备提交给应用商店

以下是我使用的配置，请仔细阅读注释。

Electron-builder打mas和mas-dev包只需要更改builderOptions.mac.type和builderOptions.mac.target.target即可(见下文示例)。这两个模式下运行与其他模式（pkg、dmg）的区别是，他们将在苹果沙盒下运行，应用将受到诸多限制。包括原本可以随意往硬盘写入文件、随意执行用户电脑上的命令行等，都将和我们开发或是打出普通安装包时的情况不同，因此在提交之前我建议先打一个mas-dev包出来并进行彻底的测试。

• 在electron中，可以通过布尔值process.mas（主进程）和remote.process.mas（渲染进程）来获取到当前应用是否在苹果沙盒模式中。

// vue.config.js
module.exports = {
  pluginOptions: {
    electronBuilder: {
      "customFileProtocol": "./", //这个解决css中用相对路径引用的文件，主要是字体
      "builderOptions": {
        "extraResources":[//所有该应用使用的外部的包都放到根目录的extraResources下，将会直接封装进安装包中
          "./extraResources/**",
          "./node_modules/@electron/remote/**", //可以解决打包后remote找不到的问题
        ], 
        "asar":false,
        "productName": "your app name",//必须添加的名称
        "appId": "com.yourapp.yourname",
        "copyright":"Copyright © yourname 2021",// 版权信息
        "directories": {
          "output": "./build" //打包后文件将会放在build文件夹下
        },
        "afterSign": "./notarize.js",
        "masDev": {
          "type":"development",
          "hardenedRuntime": false,
          "gatekeeperAssess": false,
          "entitlements": "./entitlements.mas.plist",
          "entitlementsInherit": "./entitlements.mas.inherit.plist",
          "provisioningProfile": './development.provisionprofile', //development预设，请确保已经双击安装到系统里面
        },
        "mas": {
          "type": "distribution",
          "identity": "Your Name",
          "hardenedRuntime": false,
          "entitlements": "./entitlements.mas.plist",
          "entitlementsInherit": "./entitlements.mas.inherit.plist",
          "entitlementsLoginHelper": "./entitlements.mas.loginhelper.plist", //如果需要testflight则该项必须
          "provisioningProfile": './distribution.provisionprofile', //distribution预设
        },
        "mac": {
          "identity": null, //这里必须设为null，否则electron-builder会重复签名导致应用崩溃
          "type": "development",//如果打mas包，此处为distribution；如果是masdev包，此处为development
          "icon": "./icons/icon512.icns", //你的程序图标
          "target": [{
            "target": "mas-dev", //打出什么包：mas、mas-dev
            "arch": [
              "x64",//64位Intel包，也可以填arm64（apple silicon专用）或是universal（intel和arm混合包）
            ]
          }],
          "extendInfo": {
            'ElectronTeamID': '你的teamId',
            'com.apple.developer.team-identifier': '你的teamId',
            'com.apple.application-identifier': 'xxxxxxx.com.yourapp.yourname', //你的teamid.bundleId
            'Bundle name': productName,
            'LSHasLocalizedDisplayName': true,
            "ITSAppUsesNonExemptEncryption": "NO", //出口合规证明
          },
        },
      },
    }
  },
}

第四步：打包完成后的检查

运行sudo npm run electron:build并输入密码后，electron-builder将进行打包，打出来的包在./build文件夹下。

• 再次提醒——如果我们要提交给商店，那么你应该使用mas模式打包；如果你想在苹果沙盒模式下模拟运行并进行本地测试，那么你应该使用mas-dev模式打包。很多人会忘记——直接打mas包是不能够运行的！
• 如果你选择使用mas-dev打包，这个时候是可以直接运行的，他运行在沙盒模式下，这是最接近商店应用的环境。当你开发的时候，是没有沙盒的，应用在使用一些系统级功能时并不会出现权限的限制，因此打出mas-dev包你就可以用他来检查你应用的各种权限请求、是否正常运行，特别是需要留意有些犄角旮旯里有没有哪个功能被系统拒绝权限了。一切检查完成后，你就可以打mas包来提交给苹果审核、签名和上架了（包括Testflight测试）
• mas-dev打包后的文件是一个.app文件，你可以直接双击运行他。mas-dev只能在你这台电脑上运行，因为有且只有你系统里面安装了provisionprofile。如果系统里面没有这个描述文件预设，那么你也不能运行他，会提示签名错误。不要想着直接拿这个应用包给别人使用，别人是运行不了的，这不是正确方案。如果你需要有人来帮你测试，那么请看下一条：
• mas打包后的文件里面包含一个.app文件和pkg安装包，这个.app文件是无法运行的。而那个pkg文件，你就可以通过Transporter上传到appstore，并提交审核、发放testflight测试了。如果添加Transporter后提示有错误、无法提交，那么就需要找原因了，签名错误，或是plist中没有sandbox权限等。

第五步：上传应用到AppStore

你需要到商店下载一个叫Transporter的app，登录你的账号，然后添加你刚才通过mas模式打包好的pkg文件，Transporter会自动识别应用中可能存在的错误，然后会提交到开发者中心中

第六步：完善信息，提交审核

你的应用中是有groupid和bundleid的，因此上传到商店后会自动识别到这是哪一个应用。
此时，你可以到网页里Testflight页面中看到你的应用的签名进度（通常要等半小时才会出来），然后你在这个页面上添加测试组和测试内容后，指定的测试用户就可以在Testfligt应用中看到你的应用了。

提交审核

回到商店信息页面来，你在这里可以添加版本、根据要求制作宣传海报、填写宣传文案并提交审核，这一块在网页上的引导比较明确，直接跟着他的步骤来即可。

商店页面

第七步：上架你的应用

提交审核后，苹果的审核人员会给你提出各种各样的问题需要你修改，他们会写的很详细，比如拒绝的原因、需要你提供的额外信息、甚至也提供了你可能要用到的文档等，直接按照他的要求回复或是重新打包后提交即可。

上架你的应用

反复来回几次之后，你就可以设置好价格，然后上架你的应用了！

坑点

1. 使用Transporter上传后在Testflight中显示“尚无法测试”

在electron-builder配置中必须配置entitlementsLoginHelper选项，并指向一个只包含了“com.apple.security.app-sandbox”权限的plist文件

2. electron无法使用remote模块

在electron14+中，已移除了内置的remote模块，需要另外手动安装@electron/remote模块，并手动initialize和enable。具体示例见 Electron的remote模块

3. 用启动后窗口闪烁一下即关闭

要注意，构建mas版和mas-dev版的provisioningProfile是不同的，需要分别去app store connect上生成。其中用于打mas-dev的provisioningProfile需要双击安装到系统描述文件中才能正常运行。
闪退，或是弹框提示有Code Sign错误的话，多半是签名问题，请务必检查你的plist和build config。如果你能通过Transporter上传，那么你的签名一定是没问题的。

4. electron打包好的.app直接运行后崩溃并显示签名错误

以mas模式打包好的应用是不能直接运行的，必须提交到appstore后让苹果签名，然后通过sppstore或是testflight安装才能运行。

5.无法向文件夹写入文件（writeFileSync报operation not permited）

在沙盒模式下，用户必须调用showOpenDialog或showSaveDialog选择一个文件夹之后，应用才有权限将文件保存进去，而且这个权限在关闭app后即失效，因此app每次启动都需要让用户选择一下文件夹。mas包强制要求sandbox，所以直接向用户的文件夹写入文件是不行的（app.getPath('userData')和app.getPath('temp')获取的用户文件夹不需要，因此这两个文件夹适合用来存放软件的设置、用户的操作记录、软件的应用日志等文件）。
详细介绍
但是，这个体验是很糟糕的。

举个例子，你的应用需要使用ffmpeg转码并将输出视频保存到一个用户指定的默认输出文件夹下，用户选择了一个文件夹后，写入文件的操作可以正常执行。这个时候关闭应用并重新启动应用，正常情况下你是可以再次让输出文件保存到这个目录的，但是在mas下，你是无法直接做到这一点。每次启动应用，你必须重复调用一次showOpenDialog或是showSaveDialog让用户选择一个文件夹才行。

此时就要使用Security Scoped Bookmarks (SSBs)机制来保存这个文件的地址，当应用被关闭然后再次启动时，就不用重复选择文件夹了，非常适合一些带有默认保存地址功能的应用。

具体用法：

1. 使用showOpenDialog或showSaveDialog（该功能不支持同步的文件夹选择框，必须使用异步的选择框），让用户选择一次文件夹，securityScopedBookmarks设为true

const { app, dialog } = require('electron')
const fs = require('fs')

let filepath
let bookmark

dialog.showOpenDialog(null, { 
  securityScopedBookmarks: true
}).then(({ filePaths, bookmarks }) => {
  filepath = filePaths[0]
  bookmark = bookmarks[0]
  fs.readFileSync(filepath)
})

这时候，调用完系统会返回一个bookmark，请把它保存下来。
每次启动应用，获取一下bookmark书签 文档

//background.js
app.startAccessingSecurityScopedResource(bookmark)
fs.readFileSync(filepath)

打包前记得给plist中加入bookmark的权限

<?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>
    <string>APPLE_GROUP_STRING</string>
    <key>com.apple.security.files.user-selected.read-write</key>
    <true/>
    <key>com.apple.security.files.bookmarks.document-scope</key>
    <true/>
    <key>com.apple.security.files.bookmarks.app-scope</key>
    <true/>
  </dict>
</plist>

• 注意这里的每一个filepath和bookmark是一一对应的，所以每次启动应用都需要对bookmark调用一次app.startAccessingSecurityScopedResource(bookmark)才能直接读写filepath。
• app.getPath('userData')、app.getPath('temp')这些文件夹通常拿来放临时文件还有设置之类的，是不需要让用户选择就有写入权的

6. 我想要我的程序只支持apple silicon的mac

把LSMinimumSystemVersion设置为12.0.0，arch设为arm64

"mac": {
  "target": [{
    "target": "mas",
    "arch": [
      "arm64",
    ]
  }],
  "extendInfo": {
    "LSMinimumSystemVersion": "12.0.0"
  }
}

7. 应用必须包含Dock栏

在windows上，直接调用win.removeMenu()即可将菜单栏隐藏，但是该选项对mac顶部菜单栏是无效的。mac下，每一个应用都会有顶部菜单栏，唯一的隐藏方式是调用app.dock.hide()，但是这个操作不仅隐藏了顶栏，还将dock上的图标隐藏了，但是这样做会导致你上架应用不通过。
因此我们就只能自定义一个简易菜单：

  //background.js
  import { Menu } from 'electron'
  const win = new BrowserWindow()
  if (process.platform == 'darwin') {
    Menu.setApplicationMenu(Menu.buildFromTemplate([{
      label: app.name,
      submenu: [
        { role: 'about' },
        { type: 'separator' },
        { role: 'hide' },
        { role: 'hideOthers' },
        { role: 'unhide' },
        { type: 'separator' },
        { role: 'quit' }
      ]
    }]))
  }

屏幕截图 2023-08-18 020223.png