Electron Forge 打包与分发指南：从源码到安装包的完整链路-编程实验室

Electron Forge 打包与分发指南：从源码到安装包的完整链路

【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron

导读

Electron 本身不内置任何打包与分发工具链，当你的应用在开发模式（electron .）下可以正常运行后，仍需借助额外工具才能生成可交付给用户的可分发产物（distributable）。Electron Forge 正是为此而生的官方推荐一站式工具：它将 Electron 生态中零散的打包、签名、安装包生成与发布能力统一到单一、可扩展的接口之下，让开发者不必手工拼接@electron/packager、@electron/osx-sign、electron-winstaller等底层工具。本文以 docs/tutorial/forge-overview.md 为骨架，结合本仓库中完整的分发教程、打包教程与更新教程，系统讲解 Electron Forge 的定位、核心命令（package/make/publish）、导入既有项目、代码签名、发布与自动更新，以及 electron-builder 等替代方案，帮助你打通「源码 → 安装包 → 用户机器」的完整链路。

Electron Forge 是什么：统一 Electron 构建工具生态

从本仓库的 docs/tutorial/forge-overview.md 官方指南开篇可以看到，Electron Forge 被定义为：

a tool for packaging and publishing Electron applications. It unifies Electron's build tooling ecosystem into a single extensible interface so that anyone can jump right into making Electron apps.

（一款用于打包和发布 Electron 应用的工具。它将 Electron 的构建工具生态统一进单一可扩展接口，任何人都能直接上手制作 Electron 应用。）

这段话包含两层关键信息：

打包 + 发布一体：Forge 不只负责把代码变成可执行程序，还负责把安装包发布到线上平台供用户下载。
统一而非重写：Forge 不是另起炉灶，而是把 Electron 社区成熟的核心模块（例如@electron/packager）组合到统一接口之下。正如 docs/tutorial/boilerplates-and-clis.md 中指出的，它复用的是 Slack 等 Electron 维护者同样在用的核心模块，因此 Electron 团队对底层模块的任何改进（例如打包器、签名逻辑）都会同步惠及 Forge 用户。

三个核心阶段：package、make、publish

Forge 把分发流程抽象为三个阶段，官方文档在 docs/tutorial/forge-overview.md 中将其概括为把应用从源码送到最终用户机器的全过程：

阶段	命令	产物 / 作用
package（打包）	`electron-forge package`	将应用代码与 Electron 二进制捆绑，生成一个可运行的已打包应用目录
make（制作安装包）	`electron-forge make`	基于已打包的应用目录，为每个配置的 maker 生成各平台的安装包或可执行分发包
publish（发布）	`electron-forge publish`	把 make 产出的文件发布到 GitHub Releases 等线上平台

如果你是从零开始学习 Electron，官方建议完整走一遍本仓库的入门系列教程（docs/tutorial/tutorial-1-prerequisites.md → docs/tutorial/tutorial-2-first-app.md，直到最后的打包与更新环节）；如果应用已经能在本地正常运行、只想立刻开始打包分发，那么直接进入 docs/tutorial/tutorial-5-packaging.md（即官方 6 步教程中的「第 5 步：打包你的应用」）即可——这一点在 docs/tutorial/forge-overview.md 中也有明确建议。

为什么 Electron 需要额外打包工具

在深入命令之前，先理解背景。本仓库的 docs/tutorial/tutorial-5-packaging.md 明确指出：

Electron does not have any tooling for packaging and distribution bundled into its core modules.

Electron 核心模块中没有捆绑任何打包与分发工具。一旦应用在 dev 模式跑通，你需要额外工具生成可分发产物。可分发产物分为两类：

安装包（installers）：例如 Windows 上的 MSI、Squirrel.Windows 的 Setup 程序，以及 macOS 的 DMG；
便携可执行文件（portable executables）：例如 macOS 的.app目录。

Electron Forge 通过把已有工具（@electron/packager、@electron/osx-sign、electron-winstaller等）整合进单一接口，帮你省去手工串联的负担。

实践第一步：把既有项目导入 Forge

Forge 为已有项目提供了现成的导入脚本，支持 npm 与 Yarn 两种包管理器，命令如下：

# npm npm install --save-dev @electron-forge/cli npx electron-forge import # Yarn yarn add --dev @electron-forge/cli yarn electron-forge import

导入脚本完成后，Forge 会为你的package.json注入几条脚本：

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

同时，devDependencies中会多出若干 Forge 相关包，并在项目根目录生成一个forge.config.js文件，导出一个配置对象。该配置中预置了多个 maker（生成可分发产物的包），覆盖目标平台（macOS / Windows / Linux）。

应用 package.json 的最小前提

无论是否使用 Forge，一个可打包的 Electron 应用在其package.json中至少需要声明入口文件。本仓库内置的默认应用 default_app/package.json 是极简示例：

{ "name": "electron", "productName": "Electron", "main": "main.js", "type": "module" }

Forge 打包时依赖name与version字段生成产物命名与发布版本（发布时的 release 名称即取自package.json的version字段），务必确保它们有效。

创建可分发产物：make 命令的两步流水线

执行npm run make（等价于electron-forge make）后，Forge 内部会依次完成两步：

先运行electron-forge package：把应用代码与 Electron 二进制捆绑，生成已打包目录；
再基于该目录，为每一个配置好的 maker 生成独立的分发包。

运行结束后，项目下会出现一个out目录，同时包含分发包与已打包应用目录。macOS 的输出示意如下：

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/Contents/MacOS/my-electron-app

out/make/...下的产物即为可交付的分发包（如上面的.zip）；
out/下的已打包.app目录对应package阶段产物。

out/make里的分发包已经可以直接启动分发。想要生成 DMG、deb、MSI 等不同 OS 专属格式，则需配置对应的 Maker。

通过 Maker 扩展格式

Maker 是 Forge 的可插拔机制，每种 Maker 对应一类输出格式。入门教程导出的默认配置会为各个平台预置 maker；实际项目按需取舍即可。作为对照，docs/tutorial/code-signing.md 展示了 Forge 在 Windows 侧所依赖的工具链细节：Squirrel.Windows 场景使用@electron/packager与electron-winstaller，MSI 场景则使用@electron/windows-installer同族的electron-wix-msi类工具。

例如 Windows 侧签名场景下的 maker 配置形态（详见下文代码签名小节）：

// forge.config.js module.exports = { makers: [ { name: '@electron-forge/maker-squirrel', config: { /* 该 maker 的配置 */ } } ] }

如需完整的 maker 选项清单，可查阅 docs/tutorial/tutorial-5-packaging.md 中引用的 Forge 官方 Makers 文档，以及本仓库中与其互补的 docs/tutorial/application-distribution.md（该文覆盖不做任何签名时、脱离工具链手工打包与改名的完整做法）。

分发前的必要一步：代码签名

将桌面应用分发给终端用户前，官方强烈建议进行代码签名（code signing）。代码签名是一种安全技术，用于证明桌面应用出自已知来源；Windows 与 macOS 各有一套系统级签名机制，未签名的应用会让用户的下载或启动变得困难。此外，代码签名也是教程最后一环「自动更新」的强制前提。

两平台的签名位置不同：

macOS：在应用打包层面签名；
Windows：为分发包安装器签名。

macOS：签名 + 公证配置

若已有 macOS 与 Windows 的代码签名证书，可直接写入 Forge 配置。macOS 侧在packagerConfig中同时配置osxSign与osxNotarize：

// 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 } // ... } }

这里的签名与公证分别对应底层模块@electron/osx-sign（签名）与 Apple 的notarytool（公证）。证书与账号敏感信息均通过环境变量注入，避免硬编码进仓库。更细的 macOS 签名流程可参阅 docs/tutorial/code-signing.md，其中说明 Forge 正是官方推荐的签名方式——它能同时覆盖你的应用与Squirrel.Mac/.app相关的内嵌框架。

Windows：在 maker 中指定证书

Windows 安装器签名在 maker 配置层完成，以 Squirrel.Windows maker 为例：

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

其中certificateFile指向.pfx证书文件，certificatePassword读取自环境变量。同样地，docs/tutorial/code-signing.md 强调 Electron Forge 是 Windows 侧同时签名应用与Squirrel.Windows安装器的推荐方案，其背后正是@electron/packager、electron-winstaller、electron-wix-msi这些成熟工具。

发布到 GitHub Releases 并打通自动更新

用 Publisher 自动化发布

Forge 提供Publisher（发布器）插件来把打包产物自动分发到各类线上来源，例如 GitHub Publisher。接入步骤见 docs/tutorial/tutorial-6-publishing-updating.md：

安装发布器模块（放入devDependencies）：

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

在 Forge 配置中注册发布器并填写目标仓库：

// 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 } } ] }

配置认证：Forge 默认从GITHUB_TOKEN环境变量读取令牌。官方建议创建一个只含public_repo权限范围的 Personal Access Token（PAT），仅授予对公开仓库 Releases 的写权限，并务必保密。

把 publish 命令加入 scripts：

// package.json //... "scripts": { "start": "electron-forge start", "package": "electron-forge package", "make": "electron-forge make", "publish": "electron-forge publish" }, //...

随后执行npm run publish，Forge 会运行已配置的 makers，并把产物上传为一个新的 GitHub Release。Release 名称与package.json的version字段一致。

两点实用提示：

将draft: true可先以草稿形式生成 release，人工核对产物无误、写好发布说明后再手动正式发布，避免误推送给终端用户；
默认只发布当前主机 OS 与架构下的单个产物；如需其他架构，可通过--arch参数传给 Forge 命令。

由于只能在本机平台生成对应平台的产物（例如无法在 macOS 上生成 Windows.exe），跨平台发布更推荐交给 GitHub Actions 这类可在 Ubuntu/macOS/Windows 云主机上分别运行任务的 CI 管道。这与本仓库教程中「不总是能跨平台生成产物」的提示一致。

打通自动更新

发布只是分发的一半；真正让用户无感升级需要配合 Electron 的autoUpdater模块（详见 docs/api/auto-updater.md）。Electron 维护团队为开源应用提供免费的更新服务 update.electronjs.org，其前提条件包括：应用运行于 macOS/Windows、拥有公开的 GitHub 仓库、构建产物发布在 GitHub Releases 上，且 macOS 产物已代码签名。

接入方式极为简洁：安装update-electron-app运行时依赖，并在主进程立即调用：

npm install update-electron-app

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

该模块会依据package.json的repository字段自动匹配 update.electronjs.org 的更新源。若你的应用不符合该免费服务的条件（例如仓库托管在 GitLab/Bitbucket，或仓库需保持私有），则需自建更新服务器并手工配置autoUpdater——完整方案见 docs/tutorial/updates.md。

从模板项目起步：Forge 的 Webpack 模板

如果你的项目还没有成型、也不想手工逐条配置，docs/tutorial/boilerplates-and-clis.md 还介绍了 Forge 自带的开箱即用模板：它默认以 Webpack 作为打包器，自带 TypeScript 示例配置，并提供两份配置文件便于深度定制。使用它的两个典型收益：

开箱即用：跳过多工具手写串联，直接用一条命令启动完整开发 + 构建流水线；
与官方同源：底层复用@electron/packager等社区通用核心模块，Electron 维护者（例如 Slack）的改进会同步受益于 Forge 用户。

该文同时对比了Boilerplate 与 CLI两类方案的差异，这对理解 Forge 的定位很有帮助：

Boilerplate（模板脚手架）：只是一个起点、一块「画布」，通常是以仓库形式存在的初始工程，克隆后完全按你的意愿定制；
CLI（命令行工具）：贯穿开发与发布全程持续提供支持，更「保姆式」，但同时会约束你的代码结构与构建方式。对新手而言，使用 CLI 往往帮助更大。

不选用 Forge 时的替代方案

Forge 官方文档专门以折叠块（Alternative tooling）的形式列出了不使用 Forge 时的第三方选择。这些工具由 Electron 社区成员维护，不附带 Electron 项目的官方支持。了解它们有助于你在工具选型时做出有依据的决策。

electron-builder

自诩为「打包并构建一个可分发 Electron 应用的完整解决方案」，强调一体化体验：

只需添加单个依赖，其余需求全部在内部管理，对简单度有追求；
但它会替换Electron 维护者所用的部分特性与模块（例如 auto-updater），替换后集成更紧密，却与 Atom、Visual Studio Code、Slack 这类主流 Electron 应用的实际技术栈共同点更少。

Hydraulic Conveyor

一款桌面应用分发工具，定位与特色如下：

支持在任何 OS 上交叉构建/签名所有平台包，无需配置多平台 CI；
可在应用每次启动时做同步的 web 风格更新；
无需修改代码，可用普通 HTTP 服务器承载更新；
用 Sparkle（macOS）、MSIX（Windows）、Linux 软件包仓库替换 Electron 自带自动更新器；
属于商业工具，但对开源项目免费。

面向模板爱好者的选择

在 docs/tutorial/boilerplates-and-clis.md 中还提到了社区的electron-react-boilerplate：如果你不想引入任何工具、只想要一个扎实的起步工程，它很受欢迎，内部使用electron-builder。更多工具与模板可参考社区整理的 "Awesome Electron" 清单。若列表看得眼花缭乱，也请记住：边开发边按需添加工具同样是完全可行的路线。

补充：完全脱离 Forge 的手工分发

为了加深对 Forge 所封装工作量的理解，docs/tutorial/application-distribution.md 给出了两条手工路线，它们与 Forge 自动化的能力一一对应：

预编译二进制：下载 Electron 预编译二进制，把包含package.json/main.js/index.html的应用目录命名为app，放入 resources 目录（macOS 为Electron.app/Contents/Resources/app/，Windows/Linux 为electron/resources/app）。
应用源码归档（asar）：若未使用 Parcel/Webpack 等打包器，可把源码压成app.asar放入 resources 目录，改善 Windows 等平台上的文件读取性能（具体机制另见 docs/tutorial/asar-archives.md）。

手工分发还需改名换皮（rebranding）：Windows 上可重命名electron.exe并用 rcedit 类工具改图标与版本信息；Linux 上直接重命名electron可执行文件；macOS 上需同时修改Info.plist中的CFBundleDisplayName、CFBundleIdentifier、CFBundleName，并重命名 Helper 应用。这部分正是 Forge「打包、生成安装器、签名」替你自动化的底层工作。

快速决策与求助渠道

综合以上内容，一份快速选型备忘：

你的处境	建议
新手、刚起步	走完整教程 docs/tutorial/tutorial-1-prerequisites.md，或直接用 Forge 模板脚手架
应用已在本地跑通，需要打包分发	使用`@electron-forge/cli`的`import`导入，从 docs/tutorial/tutorial-5-packaging.md 的「第 5 步」开始
需要分发到多平台并自动更新	配置对应平台的 maker、代码签名、Publisher 与`update-electron-app`（参考 docs/tutorial/tutorial-6-publishing-updating.md）
只想看打包底层机制	阅读 docs/tutorial/application-distribution.md 手工打包与改名章节
想对比工具或纯模板路线	阅读 docs/tutorial/boilerplates-and-clis.md

若在使用 Forge 时怀疑遇到 bug，可以查阅 Electron Forge 的 GitHub issue 跟踪器，确认是否已有匹配的现存 issue；若无，则可按官方 bug 报告模板提交新 issue。应用开发本身的问题则建议在 Electron 社区寻求其他开发者帮助。本仓库的 docs/README.md 是全部官方指南的目录，docs/tutorial/application-distribution.md 也从分发角度把 Forge 与 docs/tutorial/tutorial-5-packaging.md 的教程相互链接，可作为持续查阅的入口。

小结

Electron Forge 是 Electron 官方推荐的分发一体化方案，其价值可以归结为三点：

统一接口：把 package（打包）、make（生成安装包）、publish（发布）三段流水线收敛到单一、可扩展的 CLI 与配置之下；
底层复用：建立在@electron/packager等社区成熟模块之上，Electron 维护者的持续改进直接惠及 Forge 用户；
生态可选：electron-builder、Hydraulic Conveyor 等替代方案提供了不同取舍，理解差异后才能做出适合自己项目的选择。

完整的落地路径是：导入项目 →npm run make产出分发包 → 配置代码签名（macOS 公证 / Windows 证书）→ 用 Publisher 发布到 GitHub Releases → 通过autoUpdater让应用自我更新。整个过程在本仓库的系列教程 docs/tutorial/tutorial-5-packaging.md 与 docs/tutorial/tutorial-6-publishing-updating.md 中有分步讲解，配合 docs/tutorial/forge-overview.md 即可完成从源码到最终用户机器的整条链路。

【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考