05 · 打包分发：Electron Forge、签名与自动更新

目标：把开发中的应用变成可分发的安装包，发布到 GitHub Releases 并接入自动更新。官方对应：打包您的应用程序、发布和更新

为什么需要打包工具

Electron 核心不含打包能力。开发模式的应用要变成可分发文件（macOS .app/DMG、Windows MSI/exe、Linux deb），需要把应用代码 + Electron 二进制 + 依赖组合起来。Electron Forge 是官方一体化工具，底层整合了 @electron/packager、@electron/osx-sign、electron-winstaller 等。

实例：把前面的应用打包分发

Step 1：导入 Forge

npm install --save-dev @electron-forge/cli
# **将现有的 Electron 项目自动转换为一个兼容 Electron Forge 工具链的项目**
npx electron-forge import

import 脚本会自动改写 package.json：

{
  "scripts": {
    "start": "electron-forge start",
    "package": "electron-forge package",
    "make": "electron-forge make"
  }
}

并生成 forge.config.js（makers 配置，每平台一个）。

Step 2：生成可分发文件

npm run make

两步：先 electron-forge package（代码 + Electron 二进制 → 文件夹），再用各 maker 生成安装包。产物在 out/：

out/
├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip
└── out/my-electron-app-darwin-x64/my-electron-app.app/...

图标配置见 Forge 图标教程。不用 Forge 手动打包见官方应用程序打包文档。

Step 3：代码签名（强烈建议）

分发前强烈建议签名。签名证明来源可信，且是自动更新的前提。macOS 在打包时签，Windows 对可分发文件签。

macOS（forge.config.js）：

module.exports = {
  packagerConfig: {
    osxSign: {},
    osxNotarize: {
      tool: 'notarytool',
      appleId: process.env.APPLE_ID,
      appleIdPassword: process.env.APPLE_PASSWORD,
      teamId: process.env.APPLE_TEAM_ID
    }
  }
}

Windows：

module.exports = {
  makers: [
    {
      name: '@electron-forge/maker-squirrel',
      config: {
        certificateFile: './cert.pfx',
        certificatePassword: process.env.CERTIFICATE_PASSWORD
      }
    }
  ]
}

Step 4：发布到 GitHub Releases

前提：公开 GitHub 仓库 + 代码已推送。

npm install --save-dev @electron-forge/publisher-github

生成 PAT（public_repo 范围），设到环境变量 GITHUB_TOKEN（勿提交）
配置 forge.config.js：

module.exports = {
  publishers: [
    {
      name: '@electron-forge/publisher-github',
      config: {
        repository: { owner: 'github-user-name', name: 'github-repo-name' },
        prerelease: false,
        draft: true   // 先草稿，人工确认后再正式发布
      }
    }
  ]
}

加 script 并发布：

{ "scripts": { "publish": "electron-forge publish" } }

npm run publish   # 版本号取 package.json 的 version；跨架构用 --arch

本地发布只能产出当前宿主平台的安装包（mac 上出不了 .exe）。生产建议用 GitHub Actions 在 ubuntu/macOS/Windows 三端构建发布——Electron Fiddle 就是这么做的。发布前可用 npm version 自动打 tag。

关于交叉编译

边界很明确：

阶段	能否跨平台	说明
打包（package，产出裸 `.app`/应用目录）	✅ 可以	`ELECTRON_INSTALL_PLATFORM=win32 ELECTRON_INSTALL_ARCH=x64 npm install` 下载目标平台二进制后打包
生成安装包 / 签名（make）	❌ 基本不行	macOS 签名公证必须在 macOS；Windows maker 依赖 Windows（Linux + wine 能凑合但不推荐）；Linux 包同理

结论：不要在本地交叉编译，交给 CI。GitHub Actions 矩阵构建一次出三平台产物，见下方 Actions 小节。

Step 5：自动更新

官方为开源应用提供免费更新服务 update.electronjs.org，要求：

macOS 或 Windows 上运行
公开 GitHub 仓库，版本发布在 GitHub Releases
macOS 需已代码签名

接入只需两步：

npm install update-electron-app   # 注意：运行时依赖，不是 dev

// main.js
require('update-electron-app')()

原理：autoUpdater 模块检查更新源，例如 v0.28.0 会查 https://update.electronjs.org/electron/fiddle/darwin/v0.28.0。update-electron-app 模块自动读取 package.json 的 repository 字段对接。

私有仓库 / GitLab / 自建：见官方搭建更新服务器指南，自己部署更新源 + 手动配置 autoUpdater。

流程全景

开发 (electron-forge start)
  → make (package + 各平台 installer)
  → 签名 + 公证 (macOS notarize)
  → publish (GitHub Releases, 草稿→确认→发布)
  → 客户端 autoUpdater 拉取新版本自更新

练习

给应用配上自己的图标，npm run make 后安装到本机验证
建一个公开 GitHub 仓库，走一遍 publish → 草稿 → 正式发布流程
阅读 Electron Forge 文档了解 Vite/TS 模板与 makers 全列表

小结

打包分发三件套：Forge（打包+签名+发布）、GitHub Releases（托管）、update.electronjs.org 或自建源（更新）
签名不是可选项：不签名用户很难安装，也无法自动更新
多平台发布交给 CI（GitHub Actions）
下一章：06-security-performance — 生产前必读的安全与性能清单

zhaoweiguo 的知识库

目录

Electron 05 打包分发