32. Electron Forge 快速起步

写一个能跑的 Electron 应用不难，难的是把它打包成用户能双击打开的安装包。Electron 官方主推的打包工具是 Electron Forge。它把社区里零散的打包、签名、分发能力整合到一起，让你用一套配置完成从源码到安装包的整个过程。本章带你从零创建一个 Forge 工程，并弄清每个脚本在做什么。

本节目标

用 npm create electron-app@latest 一键创建工程。
认识 Forge 工程的目录结构与关键文件。
理解 start、package、make 三类脚本的区别。
找到并看懂 out/ 目录下的构建产物。
知道 Forge 在底层调用了哪些官方模块。

1-1 为什么选 Electron Forge

Electron 本身只负责运行你的代码，不包含打包功能。社区里有多种打包方案，但官方文档明确把 Electron Forge 列为推荐工具。它的优势在于「一体化」：你不需要自己拼装打包器、安装器生成器、签名工具。

Forge 在底层复用了 Electron 维护者维护的官方模块，例如 @electron/packager（负责把源码打包成各平台可执行文件）、@electron/osx-sign、@electron/notarize。这意味着 Slack、VS Code 等大型应用受益的改进，也会间接惠及你的工程。

提示：electron-builder 是另一套常见方案，它把自动更新等模块替换成了自己的实现。本教程以 Forge 为主线，electron-builder 仅作对比参考，不展开配置。

1-2 一行命令创建工程

确保本机已安装 Node.js（建议长期支持版）。在终端执行：

npm create electron-app@latest my-app

执行后，命令行会让你选择模板。Forge 目前内置四个官方模板：webpack、webpack-typescript、vite、vite-typescript。初学者直接回车选默认模板（webpack）即可。若想用 React、Vue、Angular、Svelte 等前端框架，需要在 vite 或 webpack 模板之上自行配置，或借助社区模板；Forge 并没有一个现成的「react」「vue」内置模板可供直接选择。

如果你想跳过交互、明确指定模板，可以这样写：

npm create electron-app@latest my-app -- --template=webpack-typescript

命令会在当前目录生成一个 my-app/ 文件夹。进入目录并安装依赖：

cd my-app
npm install

1-3 认识项目结构

一个 Forge 工程的结构很清晰，关键文件如下：

my-app/
├── src/
│   ├── main.js        # 主进程入口
│   ├── preload.js     # 预加载脚本
│   └── index.html     # 渲染进程页面
├── forge.config.js    # Forge 总配置
├── package.json       # 工程清单与脚本
└── node_modules/

src/main.js 是你最熟悉的主进程文件。它和前几章写的 main.js 没有区别，依然用 BrowserWindow 创建窗口、app.whenReady() 启动。不同之处在于，它现在由 Forge 负责编译和加载。

forge.config.js 是整个打包流程的中枢。这里集中配置打包参数（packagerConfig）、安装包生成器（makers）、插件（plugins）和构建钩子（hooks）。后两章会详细讲它。

打开 package.json，你会看到 Forge 自动写入的脚本：

{
  "scripts": {
    "start": "electron-forge start",
    "package": "electron-forge package",
    "make": "electron-forge make",
    "publish": "electron-forge publish"
  },
  "devDependencies": {
    "@electron-forge/cli": "^7.0.0",
    "electron": "^43.2.0"
  }
}

1-4 三类核心脚本

Forge 的工作流由几条脚本串起来，理解它们的区别非常重要。

start：开发模式。 它启动一个开发版的 Electron，加载你的源码，并开启热重载。日常写代码时一直用它：

npm run start

package：打包但未生成安装包。 它把源码打包成可直接运行的程序目录，放在 out/ 下。这一步没有生成 .dmg、.exe 这样的安装器，只是把应用「封装」好了：

npm run package

make：生成可分发的安装包。 它在 package 的基础上，调用各平台的「maker」生成真正的安装文件（如 macOS 的 .dmg、Windows 的 .exe）：

npm run make

简单记忆：start 是写代码时跑，package 是封装应用，make 是产出安装包。

1-5 看懂构建产物

运行 npm run make 后，查看 out/ 目录：

out/
├── my-app-darwin-x64/        # package 产物：可直接运行的 .app
│   └── my-app.app
└── make/                     # make 产物：安装包
    └── my-app.dmg

out/my-app-darwin-x64/my-app.app 就是封装好的应用，你可以直接双击运行。out/make/ 下才是带给用户安装的 .dmg 文件。在 Windows 上，make 会生成 .exe 安装程序；在 Linux 上则可能是 .deb 或 .rpm。

提示：out/ 目录通常体积很大，应加入 .gitignore，不要提交到版本库。

1-6 底层发生了什么

了解全貌有助于排查问题。Forge 的 make 实际做了三件事：先调用 @electron/packager 把你的源码和资源打进应用目录；再用 makers 生成对应平台的安装包；若配置了签名，还会调用 @electron/osx-sign 或 @electron/windows-sign。

你写的 forge.config.js 只是「声明意图」，真正的重活由这些官方模块完成。这也解释了为什么 Forge 的配置字段很多直接对应 @electron/packager 的选项。

1-7 常见问题

新手常卡在模板选择上。如果你的应用是纯 JavaScript，选 webpack 就够了；用 TypeScript 就选 webpack-typescript；要用 React/Vue 等前端框架，则选对应的 react/vue 模板。

另一个常见困惑是 package 和 make 的区别。记住：package 只是把应用封好，make 才产出安装器。调试打包结果时，先看 package 产物能否运行，再排查 make 阶段。

1-8 把已有项目接入 Forge

若你已有一个用纯 electron 跑起来的工程，想改用 Forge，步骤很轻。先安装 CLI：npm install --save-dev @electron-forge/cli，再执行 npx electron-forge import。它会自动改写 package.json 的脚本、生成 forge.config.js、补上 FusesPlugin。原 main.js、preload、页面无需改动，Forge 只是接管了「运行与打包」的方式。

注意 import 不会替你处理前端打包。若原先靠 webpack 之类手动构建，需要在 plugins 里配置对应的打包插件（如 @electron-forge/plugin-webpack），让 Forge 在 start 与 make 时自动构建。这一步是老项目迁移最常见的卡点。

常见误区

误以为 make 一次能产出全平台安装包。Electron 不原生支持交叉编译安装器，需在对应系统上分别 make。
误以为 package 产物可直接分发。它只是封装好的应用目录，用户要的是 make 生成的安装器。
把 out/ 提交进版本库。它体积大且每次重建，应加入 .gitignore。

1-9 清理与版本锁定

反复 make 会在 out/ 累积内容。若行为异常，先删 out/ 再构建，可排除旧产物干扰。Forge 不维护全局缓存，但打包器缓存可能导致「改了不生效」，必要时清除对应缓存目录。Electron 版本由 package.json 的 electron 字段决定，升级时改这里并重装即可，Forge 自动跟随，切勿在多处写死版本。

小结

本章你用一行命令创建了 Forge 工程，并分清了 start、package、make 三类脚本。Forge 把打包、生成安装包、签名整合成统一配置，是官方推荐的打包主线。下一章我们深入 forge.config.js，配置 asar 归档、图标与额外资源。