企业官网建设流程全解析

• 开发工具
• 桌面应用
• 前端构建

@electron-forge/maker-pkg是 Electron Forge 官方提供的 macOS 安装包生成器，它将已打包好的 Electron 应用制作为.pkg扁平安装包（flat package installer），既可用于上传 Mac App Store（MAS 上架），也可作为 macOS 用户的替代分发方式。读完本文，你将掌握maker-pkg的安装、配置、安装脚本注入、签名与公证（notarization）以及调试方法，并了解其底层实现原理。

一、什么是 .pkg 安装包

.pkg是 macOS 平台的标准安装包格式。Electron Forge 的 pkg maker 会调用 Apple 官方工具链，把一个已经过electron-packager打包的.app应用封装为可双击安装的.pkg文件，用户双击后即可通过系统安装向导完成安装（默认安装到/Applications）。

该格式在历史上也被称为扁平安装包：在 Mac OS X Leopard（10.5）之前，安装包以分层目录形式组织；Leopard 引入了现代.pkg所使用的扁平包格式。苹果官方对扁平包规范的文档化程度较低，如需深入其内部结构，可以参考社区文章（如 Stéphane Sudre 的Flat Package Format - The missing documentation与 MacTech 的The Flat Package系列）。

本文档对应的官方用法说明见 docs/config/makers/pkg.mdx，包源码见 packages/maker/pkg，核心实现位于 MakerPKG.ts。

二、使用前提与平台限制

maker-pkg有两个硬性限制：

1. 只能在 macOS 机器上构建：源码中通过isSupportedOnCurrentPlatform()直接检查process.platform === 'darwin'（见 MakerPKG.ts），因此在 Linux、Windows 主机上该 maker 会被判定为不可用。

2. 只能面向darwin或mas平台目标：defaultPlatforms定义为['darwin', 'mas']。make()方法第一步会调用isValidTargetPlatform()做校验，若传入其他平台（如win32）会直接抛出错误：

   The pkg maker only supports targeting "mas" and "darwin" builds. You provided "win32".

   对应测试用例见 MakerPKG.spec.ts。

其中mas平台意味着目标是 Mac App Store 发布，darwin则对应常规的开发者签名分发。

三、安装

在项目根目录执行：

npm install --save-dev @electron-forge/maker-pkg

当前仓库中该包的版本为 8.0.1（见 package.json），其运行时依赖为@electron-forge/maker-base、@electron-forge/shared-types、@electron/notarize与@electron/osx-sign，Node.js 版本要求>= 22.13.0。

四、基础配置

在forge.config.js（或package.json的config.forge字段）的makers数组中注册该 maker：

// forge.config.js module.exports = { makers: [ { name: '@electron-forge/maker-pkg', config: { keychain: 'my-secret-ci-keychain' } } ] };

与所有 maker 一样，config既可以是对象，也可以是一个接收当前目标架构arch并返回配置对象的函数（见 docs/config/makers/index.mdx 中的通用写法）。上例中的keychain常用于 CI 环境：当签名证书存放在自定义钥匙串（keychain）中而非系统默认钥匙串时，指定其名称即可让签名工具正确查找证书。

五、MakerPKGConfig 完整配置项

所有配置项均为可选项，完整定义见 Config.ts。下表汇总了每个字段的作用与默认值：

name：控制产物文件名

若不设置，产物文件名由应用名、版本号与目标架构三部分组成。例如应用名为My Test App、版本为1.2.3、目标架构为arm64时，默认文件名为My Test App-1.2.3-arm64.pkg。这一行为被测试用例明确验证（见 MakerPKG.spec.ts）。

scripts：注入安装前后脚本

maker-pkg支持在应用安装前、后分别执行一个 bash 脚本。你可以利用preinstall脚本做依赖检查、清理旧版本等准备工作，利用postinstall脚本做权限调整、注册启动项等收尾工作。使用它们需要满足三个条件：

1. 脚本文件必须具有执行权限（如chmod +x）；
2. 脚本文件不能带扩展名（即文件名为preinstall、postinstall，而不是preinstall.sh）；
3. 两个脚本必须位于同一目录中。

推荐的做法是在项目根目录下建一个scripts文件夹：

my-app ├─── forge.config.js └─── scripts ├── postinstall └── preinstall

然后在配置中把scripts指向该目录（注意使用node:path解析绝对路径，保证相对定位正确）：

const path = require('node:path'); module.exports = { makers: [ { name: '@electron-forge/maker-pkg', config: { scripts: path.join(__dirname, 'scripts') } } ] };

六、底层实现：make() 的执行流程

MakerPKG继承自MakerBase（见 packages/maker/base/src/Maker.ts），其make()方法在 MakerPKG.ts 中实现了完整流程，大致分为四步：

1. 平台校验：拒绝darwin/mas之外的所有目标平台。
2. 确定输出路径：产物写入`${makeDir}/pkg/${targetArch}/${name}.pkg`。其中makeDir是 Forge 分配的产品输出目录，targetArch单独作为子目录，目的是避免多个并行 maker（如同时构建不同架构）之间产物互相冲突。这一行为同样有测试覆盖（见 MakerPKG.spec.ts）。
3. 调用flat()封装安装包：flat来自@electron/osx-sign，它接收一个合并后的配置对象{ ...this.config, app, pkg, platform }，其中app指向打包产物`${dir}/${appName}.app`，pkg为输出路径，platform为当前目标平台。
4. 条件公证（notarization）：当同时满足「配置了identity签名身份」且「forgeConfig.packagerConfig.osxNotarize已配置」两个条件时，调用@electron/notarize的notarize()对生成的.pkg进行 Apple 公证，并把osxNotarize的全部配置透传，额外追加appPath: outPath指向产物。

公证的条件逻辑在测试中有清晰印证：只有 identity 与osxNotarize同时存在时才触发公证，缺任何一个都不会调用（见 MakerPKG.spec.ts）。这意味着：

• 仅配置osxNotarize（如在packagerConfig中设置了osxNotarize与 Apple ID）但未设置identity，则不会对.pkg公证；
• 若要发布到 Mac App Store 或进行 Gatekeeper 友好的分发，两者应同时配置。

七、签名与公证实践

macOS 分发与上架绕不开代码签名与公证。在使用maker-pkg时，签名工作实际上由flat()底层完成——它会使用identity、keychain、identityValidation、install等配置进行签名与安装路径设置。CI 场景下常见组合如下：

module.exports = { packagerConfig: { osxNotarize: { appleId: 'me@example.com', appleIdPassword: '@keychain:AC_PASSWORD', teamId: 'TEAM123' } }, makers: [ { name: '@electron-forge/maker-pkg', config: { identity: 'Developer ID Installer: My Company (XXXXXXXXXX)', keychain: 'my-secret-ci-keychain', identityValidation: true, install: '/Applications' } } ] };

需要说明的是，appleIdPassword使用@keychain:...引用式写法可避免把密码明文写进配置。公证过程需要联网提交给 Apple 服务，请确保 CI 环境网络可达，且 Apple ID 已开启双重认证所需的 app 专用密码。

八、调试与日志

.pkg安装器本身运行于 macOS 系统安装框架，其日志统一记录在系统安装日志中：

• 日志文件路径：/var/log/install.log
• 图形界面查看：使用 macOS 自带的Console.app实用工具

若需要排查签名阶段的问题，可为本 maker 开启底层签名库的调试输出：

DEBUG=electron-osx-sign* electron-forge make

该环境变量会输出electron-osx-sign的详细日志，帮助定位证书选择、签名失败等常见问题。

九、验证与测试

仓库中 MakerPKG.spec.ts 使用 Vitest 对该 maker 做了 mock 化的单元测试，覆盖以下关键行为，可作为理解其契约的参考：

• 默认参数透传：flat收到app、pkg（含My Test App-1.2.3-<arch>.pkg）、platform；
• 按架构分目录输出产物，避免并行 maker 冲突；
• 非法平台（win32）抛出明确错误；
• 公证的触发条件（identity 与osxNotarize缺一不可）。

十、总结

@electron-forge/maker-pkg把「打包.app→ 生成.pkg安装包 → 按需公证」这条 macOS 发布链路浓缩为一个 maker 配置。在 macOS 主机上、面向darwin/mas平台运行时，你只需要在makers数组中登记该 maker，并视需要配置keychain、identity、scripts等选项，即可获得可直接分发或上架的.pkg产物。若需要更多 maker 的对比与通用配置方式，可参考 docs/config/makers/index.mdx 与 docs/config/configuration.mdx。

• 开发工具
• 桌面应用
• 前端构建