HUA

macOS 应用构建，看似近在咫尺，实则坑坑致命。

打包

在package.json中，dependencies会被打进 Electron 应用的包里，而devDependencies则不会，所以必要的依赖需要放到dependencies中。files中定义自己需要被打进 Electron 包里的文件。以下是一个完整的 mac electron-builder的配置文件。

 1const base = {
 2  appId: 'com.xxxx.xxxx', 
 3  productName: 'Electron 打包模版', 
 4  icon: './media/images/icon.ico',
 5  files: [  
 6    'main.js',
 7    'bundles',
 8    'updater/win/index.html',
 9    'updater/build/bootstrap.js',
10    'updater/mac/Updater.js',
11    'updater/mac/index.html'
12  ],
13  publish: { 
14    provider: 'generic', 
15    url: '' 
16  },
17  mac: {
18    target: [  
19      "dmg",
20      "zip",
21      "pkg",
22      "mas"
23    ],
24    icon: 'media/images/icon.icns',
25    hardenedRuntime: true,
26    entitlements: 'electron-builder/entitlements.plist',  
27    entitlementsInherit: 'electron-builder/entitlements.plist',
28    provisioningProfile: 'electron-builder/comalibabaslobs.provisionprofile'
29  },
30  pkg: {
31    isRelocatable: false,
32    overwriteAction: "upgrade",
33  },
34  mas: {
35    icon: 'media/images/icon.icns',
36    hardenedRuntime: true,
37    entitlements: 'electron-builder/entitlements.mas.plist',
38    entitlementsInherit: 'electron-builder/entitlements.mas.plist',
39  },
40  dmg: {
41    background: 'media/images/dmg-bg.png',
42    icon: 'media/images/icon.icns',
43    iconSize: 100,
44    sign: false,
45    contents: [ 
46      {
47        x: 112,
48        y: 165,
49      },
50      {
51        type: 'link',
52        path: '/Applications',
53        x: 396,
54        y: 165,
55      },
56    ],
57  },
58  extraMetadata: {  
59    env: 'production',
60  }
61};
62
63module.exports = base;

签名

MacOS 10.15 之前，应用如果没有进行签名，首次打开的时候就会出现“恶意软件”提示。

1. 加入开发者

加入 Apple Developer Program(需要缴纳年费)

如果是管理员，会看到可以申请 Developer ID Application，如果不是管理员就会像我这种，看到是灰色的。Electron 打包是需要用这个身份生成证书的。

2. 生成签名证书

如果有管理员权限，点击生成新的证书。

Choose File 里面的文件从哪里来？打开 mac 的钥匙串访问 -> 证书助理 -> 从证书颁发机构请求证书，这里生成了 CertificateSigningRequest.certSigningRequest 的文件，这个文件可以被多次用来生成 mac 证书。

填写必要信息，用户邮箱填写你的 app开发者邮箱，常用名称随便取一个，然后选择保存到本地磁盘。

3. 安装签名证书

上次文件后就生成证书了，下载证书安装。如果出现了次证书不受信任的情况，在列表中双击证书，将使用此证书时更改为始终信任。

如果安装的证书不对，会出现 Command failed: codesign ...

4. 证书导出 p12 给其它人使用

在 mac 的钥匙串访问中，找到证书，然后 右键 -> 导出证书，一般导出 .p12 形式，然后输入证书安装的密码。其它人拿着你的证书，告诉他安装密码即可安装。

5. 不要 Developer ID Application 签名证书，不影响 Electron 应用打包

在打包过程中，找不到 Developer ID Application 签名证书的情况下，会跳过处理。但是应用不签名和公证会影响electron-autoupdater 自动更新能下载无法打开，用户首次打开会提示恶意软件，应用无法上架到appStore。

公证

MacOS 10.14.5 之后，应用如果没有进行公证（将安装包上传到 Apple 审查），首次打开的时候就会出现更严重的“恶意软件”提示。没有进行过公证也无法上传到 Apple Store 中提供给其他人下载。

代码公证

 1const { notarize } = require('electron-notarize');
 2notarize({
 3  appPath: '',          
 4  appBundleId: '',      
 5  appleId: '',          
 6  appleIdPassword: '',  
 7  ascProvider: ''       
 8})

  1. appPath打包后应用的路径，.app 或者 .dmg 结尾。

  2. appBundleId 跟 Electron-builder 配置的 appId 一致，这个 appId 要妥善命名。不要发布应用以后再修改，不然会导致应用无法自动更新。比较好的命名一般都是 com.xxx（公司名）.xxx（应用英文名）

  1. 苹果开发者的账号 appleId，填写自己的开发者id 就可以，确保自己是属于开发者。应用专用密码 appleIdPassword，登录 appleid.apple.com/account/man…

这个密码生成后只会出现一次，之后再也没办法看到，所有请保存下来。如果忘记了密码，就重新创建一个，为方便管理不用的密码进行删除后重新创建比较合适。

  1. ascProvider 证书的提供者，通过 mac 钥匙串访问查看。你所有使用的签名证书，括号里面的就是证书提供者。

  1. 公证会把程序压缩包上传到 apple 服务器，保证网络通畅。公证成功后，开发者邮箱会收到邮件。

  1. notarize {}后面是绝对的json结构，不要出现这些是单引号的情况，不然会报错。 appPath，appBundleId，appleIdPassword，ascProvider

命令行工具公证

需要下载 xcode。

  1. 一句话命令公证
 1xcrun altool --notarize-app --primary-bundle-id "com.xxx.xxx" --username "your developer appleid" --password "appleId-password" --asc-provider "ProviderShortname" -t osx --file xxx.dmg
  • “com.xxx.xxx”：在苹果开发者注册的id

  • your developer appleid：你登录的苹果开发者id
  • app-password：你登录的苹果开发者的应用专用密码
  • “ProviderShortname”：

  1. ascProvider 证书的提供者命令行查询
 1xcrun altool --list-providers -u "apple id" -p "appleIdPassword(应用专用密码)”
 2
  1. 公证成功后
 1No errors uploading 'xxxxxxx-xxxx.dmg'.
 2RequestUUID = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

上架 AppStore 商店

Electron 应用如果要能发到 appStore，需要 electron-builder 构建 mas（Mac应用商店），经过签名公证后上传到 app store connect，上传之前应用需要支持sandbox。

注册AppId

在 electron-builder 配置的 appId，无论写什么我们都是可以打包配置成功的，因为不涉及到发到 appStore。如果需要发到 appStore，就需要到 apple 开发者官网中去申请一个正式的了。

沙盒配置

在 entitlements.mas.plist 配置写入如下代码 com.apple.security.app-sandbox 进行沙盒配置。

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

打包配置

mac 打包配置 mas 信息，需要在 mac 中配置 target:["mas"]。mas:{}设置，并且需要 provisioningProfile，这些都会报错。

 1...
 2mac: {
 3    target: [
 4      "mas"
 5    ],
 6    icon: 'media/images/icon.icns',
 7    hardenedRuntime: true,
 8    entitlements: 'electron-builder/entitlements.plist',
 9    entitlementsInherit: 'electron-builder/entitlements.plist',
10    provisioningProfile: 'electron-builder/comalibabaslobs.provisionprofile'
11},
12mas: {
13    icon: 'media/images/icon-1688.icns',
14    hardenedRuntime: true,
15    entitlements: 'electron-builder/entitlements.mas.plist',
16    entitlementsInherit: 'electron-builder/entitlements.mas.plist'
17 }
18...

证书申请

在苹果开发者 Certificates 申请这两个证书，并且安装。在打包 mas 包的时候，会自动寻找这两个证书进行签名。

  • 3rd Party Mac Developer Application（Mac 提交证书）

  • 3rd Party Mac Developer Installer（Mac 安装程序证书，苹果发行版或第三方Mac开发者应用程序）

配置文件

在苹果开发者 Profiles 申请 Mac App Store 配置信息。并且在打包配置中主动使用此配置信息 provisioningProfile: 'electron-builder/comalibabaslobs.provisionprofile'

 1...
 2mac: {
 3    ...
 4    provisioningProfile: 'electron-builder/comalibabaslobs.provisionprofile'
 5    ...
 6}
 7...
 8

 1
 2$ cd ~/Library/MobileDevice/Provisioning\ Profiles/ 
 3打开访达 -> 顶部导航栏 前往 -> 前往文件夹 -> 输入~/Library/MobileDevice/Provisioning\ Profiles/，点击前住
 4
 5
 6打开Xcode,进入Preferences->Accounts,选择对应的Apple ID。 点击Download Manual Profiles,描述文件就会马上出现在刚才打的目录里面。
 7

上传应用包

苹果出的上传工具 Transporter，可在 appStore 下载，上传的格式为 pkg 或者 ipa 格式。找到 mas 下的 pkg 包进行上传。

Transporter 软件点交付，会先经过验证，然后上传，如果出错，会给出具体原因。以下是常见的签名错误，检查自己的证书和配置是否正确。

添加测试

在苹果应用管理网站中会看到自己上传的应用，Transporter上传到网站里看到会有延时，不要误以为是没有成功。所有上传的文件会到 TestFlight，经过验证后，就可以添加内部或者外部测试人员。之后在 App Store里构建正式对外版本。

应用图标（windows & macOS）

  1. 准备一个 1024 * 1024 的 png 图片
  2. 线上 png 转 ico 和 icns（目前线上转 icns 会有点问题，建议是使用 iconutil 工具进行转换）
 1ico：window图标  https:
 2ico 至少要 256 x 256，如果线上地址转成 256x256 的就可以了，转 512x512 有可能转不出来。
 3
 4icns：mac图标    https:
  1. mac 有些时候还需要做一个安装图片 在打开 mac 应用后，需要用户把左侧的应用图标拖拽到右侧，应用会被安装在 mac 应用程序中。例如：

Q&A

1、在进行mas签名的时候，自签名证书会出错，考虑重新安装下证书，直到这个证书默认有效。

 13rd Party Mac Developer Application: Hangzhou xxxxx Advertising Co., Ltd. (xxxxxxx): this identity cannot be used for signing code

2、app 交付到 mac store，需要申请 Mac App Distribution 和 Mac Installer Distribution 证书。

安装后如下，应该默认证书有效，而不是需要手动信任的。

首先进行开发者ID进行签名，如果应用需要上架到AppStore，则需要生成mas，再进行 Mac App Distribution 和 Mac Installer Distribution 分发签名。

3、交付失败，证书签名错误。代码签名无效，必须使用配置文件中包含的证书进行签名。

查看 profile 配置

 1provisioningProfile:

如下方式生成： Profiles -> Mac App Store -> 选择注册的ID -> 选择签名用的 Mac App Distribution

选择签名用的 Mac App Distribution，查看下是否用这个证书进行签名的。签名证书里面查看 Mac App Distribution，确认本地用哪个证书进行签名的。虽然证书名称一致，后面的过期时间可以分辨安装的不同证书。

4、没有公证的 pkg 包可以进行交付么？

用 Transporter 交付 pkg 包到 appleStore，不需要进行公证。公证的作用是为了安装时候 mac 信任此软件。

总结

  1. mac 上首次安装不出现“恶意软件”提示，需要对应用进行签名和公证两步操作。
  2. mac 进行签名和公证后，用 electron autoUpdater 进行自动更新，就能够下载和安装，如果没有进行签名和公证，或者只进行了签名，都是只能下载，但是无法自动安装和打开。
  3. mac 上 4 个证书，自己分发申请 Developer ID Application 并进行公证即可，如果需要上架到 AppStore，需要申请 Mac Installer Distribution 和 Mac App Distribution。
    • 开发不需要签名和公证申请 Mac Developer 或者 Apple Development
    • 开发需要签名和公证申请 Developer ID Application
    • 上架AppStore申请 Mac Installer Distribution
    • 上架AppStore申请 Mac App Distribution
  4. mac 开发必用的两个网站，第一个开发使用，第二个应用发布使用。
  5. 一些打包配置信息官网可查，一定要学会看官方文档。 electron-builder 官网
  6. 小技巧：appid 和 应用专用密码可以存到环境变量中。node用process.env读取。
 1
 2cat ~/.bash_profile
 3
 4vi ~/.bash_profile
 5
 6例如：bash_profile文件：
 7export LC_ALL=en_US.UTF-8
 8读取：process.env['LC_ALL']

参考

解释了apple 开发的概念：learn.microsoft.com/zh-cn/appce…

个人笔记记录 2021 ~ 2025