desktop-packaging-electron-forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Electron Forge Packaging

Electron Forge 打包

Quick Guide: Electron Forge v7 is the official Electron build toolchain. Configure via
forge.config.ts
with typed imports from
@electron-forge/shared-types
. Use makers to produce platform-specific installers (Squirrel for Windows, DMG/ZIP for macOS, deb/rpm for Linux). Use publishers to upload artifacts (GitHub Releases, S3, Snapcraft). Always code-sign production builds -- macOS requires both signing and notarization. Enable Electron Fuses to harden the binary at package time. Use hooks (
prePackage
,
postMake
) for custom build logic. Electron itself MUST be a
devDependency
-- Forge bundles only
dependencies
.

<critical_requirements>

快速指南： Electron Forge v7 是官方的 Electron 构建工具链。通过
forge.config.ts
进行配置，可从
@electron-forge/shared-types
导入类型化模块。使用 makers 生成特定平台的安装程序（Windows 用 Squirrel，macOS 用 DMG/ZIP，Linux 用 deb/rpm）。使用 publishers 上传构建产物（GitHub Releases、S3、Snapcraft）。生产环境构建必须进行代码签名——macOS 同时需要签名和公证。启用 Electron Fuses 可在打包时加固二进制文件。使用 钩子（hooks）（
prePackage
、
postMake
）实现自定义构建逻辑。Electron 必须作为
devDependency
——Forge 仅打包
dependencies
中的依赖。

<critical_requirements>

CRITICAL: Before Using This Skill

重要提示：使用本技能前须知

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type
, named constants)

(You MUST place
electron
in
devDependencies
-- Forge provides the Electron binary during packaging; placing it in
dependencies
bloats the app by ~200MB)

(You MUST code-sign macOS builds with
osxSign
and
osxNotarize
in
packagerConfig
-- unsigned apps are blocked by Gatekeeper on macOS 10.15+)

(You MUST enable
asar: true
in
packagerConfig
-- without ASAR, your source code ships as plain-text files readable by any user)

(You MUST store signing credentials in environment variables -- never hardcode secrets in
forge.config.ts
)

(You MUST enable Fuses (
FuseV1Options.RunAsNode: false
,
OnlyLoadAppFromAsar: true
) for production security -- without them, attackers can bypass ASAR integrity and run arbitrary Node.js code)

</critical_requirements>

Auto-detection: Electron Forge, electron-forge, forge.config.ts, forge.config.js, @electron-forge, maker-squirrel, maker-dmg, maker-deb, maker-rpm, maker-zip, maker-flatpak, maker-snap, maker-appx, maker-wix, maker-pkg, maker-msix, publisher-github, publisher-s3, publisher-snapcraft, plugin-vite, plugin-webpack, plugin-fuses, FusesPlugin, osxSign, osxNotarize, electron-forge make, electron-forge publish, electron-forge package

When to use:

Configuring
```
forge.config.ts
```
for packaging and distribution
Choosing and configuring makers for target platforms
Setting up publishers for automated release distribution
Code signing macOS (notarization) or Windows (Authenticode) builds
Enabling Electron Fuses for binary hardening
Adding build hooks for custom pre/post-packaging logic
Setting up CI/CD pipelines for cross-platform builds
Deciding between Electron Forge and electron-builder

When NOT to use:

Electron app architecture (main/renderer process, IPC, preload) -- use the Electron framework skill
Choosing or configuring a bundler for renderer code in isolation
Auto-update implementation (that is an Electron framework concern, not a Forge concern)
UI framework selection for renderers

Key patterns covered:

forge.config.ts structure with typed configuration
Platform-specific maker selection and configuration
macOS code signing + notarization setup
Windows Authenticode signing (traditional + Azure Trusted Signing)
Fuses plugin for binary hardening
Publisher configuration (GitHub, S3, Snapcraft)
Build hooks and lifecycle
CI/CD cross-platform build matrix
Forge vs electron-builder decision framework

所有代码必须遵循 CLAUDE.md 中的项目规范（短横线命名法、命名导出、导入顺序、
import type
、命名常量）

（必须将
electron
放在
devDependencies
中——Forge 在打包期间会提供 Electron 二进制文件；若放在
dependencies
中，应用体积会膨胀约 200MB）

（必须在
packagerConfig
中配置
osxSign
和
osxNotarize
对 macOS 构建进行代码签名——未签名的应用会被 macOS 10.15+ 的 Gatekeeper 拦截）

（必须在
packagerConfig
中启用
asar: true
——若不启用 ASAR，源代码会以明文文件形式交付，任何用户都可读取）

（必须将签名凭证存储在环境变量中——切勿在
forge.config.ts
中硬编码密钥）

（生产环境必须启用 Fuses（
FuseV1Options.RunAsNode: false
、
OnlyLoadAppFromAsar: true
）以保障安全——若不启用，攻击者可绕过 ASAR 完整性校验并运行任意 Node.js 代码）

</critical_requirements>

自动检测项： Electron Forge、electron-forge、forge.config.ts、forge.config.js、@electron-forge、maker-squirrel、maker-dmg、maker-deb、maker-rpm、maker-zip、maker-flatpak、maker-snap、maker-appx、maker-wix、maker-pkg、maker-msix、publisher-github、publisher-s3、publisher-snapcraft、plugin-vite、plugin-webpack、plugin-fuses、FusesPlugin、osxSign、osxNotarize、electron-forge make、electron-forge publish、electron-forge package

适用场景：

配置
```
forge.config.ts
```
用于打包和分发
为目标平台选择并配置生成器（makers）
设置发布器（publishers）实现自动化版本分发
为 macOS（公证）或 Windows（Authenticode）构建进行代码签名
启用 Electron Fuses 加固二进制文件
添加构建钩子实现自定义打包前后逻辑
搭建跨平台构建的 CI/CD 流水线
在 Electron Forge 和 electron-builder 之间做选择

不适用场景：

Electron 应用架构（主进程/渲染进程、IPC、预加载脚本）——请使用 Electron 框架技能
单独选择或配置渲染进程的打包工具
自动更新实现（属于 Electron 框架范畴，而非 Forge）
为渲染进程选择 UI 框架

涵盖的核心模式：

带类型化配置的 forge.config.ts 结构
特定平台生成器的选择与配置
macOS 代码签名 + 公证设置
Windows Authenticode 签名（传统方式 + Azure Trusted Signing）
用于二进制加固的 Fuses 插件
发布器配置（GitHub、S3、Snapcraft）
构建钩子与生命周期
CI/CD 跨平台构建矩阵
Forge 与 electron-builder 的决策框架

Philosophy

设计理念

Electron Forge is a unified build pipeline that composes first-party Electron tools (

@electron/packager

@electron/rebuild

@electron/osx-sign

@electron/notarize

@electron/fuses

) into a single workflow. Rather than reimplementing build logic, Forge orchestrates existing tools through three steps:

Package --
```
@electron/packager
```
creates the platform-specific app bundle (.app, .exe)
Make -- Makers transform the bundle into distributable installers (.dmg, .msi, .deb)
Publish -- Publishers upload make artifacts to distribution targets (GitHub, S3)

Why Forge over alternatives:

First-party: maintained by the Electron team, receives new features (ASAR integrity, universal macOS builds) as soon as they ship
Composable: makers, publishers, and plugins are independent npm packages
TypeScript-native:
```
forge.config.ts
```
with full type inference since v7

Key constraint: Forge runs makers only for the current host OS by default. Cross-platform builds require CI/CD with per-platform runners (macOS for .dmg, Windows for .exe, Linux for .deb).

</philosophy>

Electron Forge 是一个统一的构建流水线，它将官方 Electron 工具（

@electron/packager

、

@electron/rebuild

、

@electron/osx-sign

、

@electron/notarize

、

@electron/fuses

）组合成单一工作流。Forge 并非重新实现构建逻辑，而是通过三个步骤协调现有工具：

打包——
```
@electron/packager
```
创建特定平台的应用包（.app、.exe）
生成——生成器（makers）将应用包转换为可分发的安装程序（.dmg、.msi、.deb）
发布——发布器（publishers）将生成的产物上传到分发目标（GitHub、S3）

为何选择 Forge 而非其他工具：

官方维护：由 Electron 团队维护，新功能（如 ASAR 完整性校验、macOS 通用构建）一经推出即可使用
可组合性：生成器、发布器和插件都是独立的 npm 包
TypeScript 原生支持：v7 版本起，
```
forge.config.ts
```
具备完整的类型推断

核心限制： 默认情况下，Forge 仅在当前宿主操作系统运行生成器。跨平台构建需要使用 CI/CD 并配备对应平台的运行器（macOS 用于生成 .dmg，Windows 用于生成 .exe，Linux 用于生成 .deb）。

</philosophy>

Core Patterns

核心模式

Pattern 1: forge.config.ts Structure

模式 1：forge.config.ts 结构

The configuration file defines packaging options, makers, publishers, plugins, and hooks. All fields are optional.

typescript

import type { ForgeConfig } from "@electron-forge/shared-types";
import { FusesPlugin } from "@electron-forge/plugin-fuses";
import { FuseV1Options, FuseVersion } from "@electron/fuses";

const config: ForgeConfig = {
  packagerConfig: {
    asar: true,
    icon: "./assets/icon", // omit extension -- Forge picks .icns/.ico/.png
    name: "MyApp",
    executableName: "my-app",
    appBundleId: "com.example.myapp",
  },
  makers: [
    /* see Pattern 2 */
  ],
  publishers: [
    /* see Pattern 5 */
  ],
  plugins: [
    /* see Pattern 4 */
  ],
  hooks: {
    /* see Pattern 6 */
  },
};

export default config;

Key constraint: You cannot override

dir

arch

platform

out

, or

electronVersion

packagerConfig

-- Forge sets these internally.

See examples/core.md for full configuration with makers, signing, and fuses.

配置文件定义打包选项、生成器、发布器、插件和钩子。所有字段均为可选。

typescript

import type { ForgeConfig } from "@electron-forge/shared-types";
import { FusesPlugin } from "@electron-forge/plugin-fuses";
import { FuseV1Options, FuseVersion } from "@electron/fuses";

const config: ForgeConfig = {
  packagerConfig: {
    asar: true,
    icon: "./assets/icon", // 无需扩展名——Forge 会自动选择 .icns/.ico/.png
    name: "MyApp",
    executableName: "my-app",
    appBundleId: "com.example.myapp",
  },
  makers: [
    /* 参见模式 2 */
  ],
  publishers: [
    /* 参见模式 5 */
  ],
  plugins: [
    /* 参见模式 4 */
  ],
  hooks: {
    /* 参见模式 6 */
  },
};

export default config;

核心限制： 无法在

packagerConfig

中覆盖

dir

、

arch

、

platform

、

out

或

electronVersion

——这些由 Forge 内部设置。

完整配置示例（含生成器、签名和 Fuses）请查看 examples/core.md。

Pattern 2: Maker Selection by Platform

模式 2：按平台选择生成器

Each maker produces a specific installer format for a target OS. Install only the makers you need.

Maker	Package	Platform	Output
Squirrel.Windows	`@electron-forge/maker-squirrel`	Windows	`.exe` (auto-updating)
WiX MSI	`@electron-forge/maker-wix`	Windows	`.msi`
MSIX	`@electron-forge/maker-msix`	Windows	`.msix`
AppX	`@electron-forge/maker-appx`	Windows	`.appx` (Microsoft Store)
DMG	`@electron-forge/maker-dmg`	macOS	`.dmg`
PKG	`@electron-forge/maker-pkg`	macOS	`.pkg` (Mac App Store)
ZIP	`@electron-forge/maker-zip`	macOS, Linux	`.zip`
deb	`@electron-forge/maker-deb`	Linux	`.deb` (Debian/Ubuntu)
RPM	`@electron-forge/maker-rpm`	Linux	`.rpm` (Fedora/RHEL)
Flatpak	`@electron-forge/maker-flatpak`	Linux	`.flatpak`
Snap	`@electron-forge/maker-snap`	Linux	`.snap`

Recommended starter set: Squirrel (Windows) + DMG + ZIP (macOS) + deb (Linux).

See examples/core.md for maker configuration examples.

每个生成器为目标操作系统生成特定格式的安装程序。仅安装所需的生成器即可。

生成器	包名	平台	输出格式
Squirrel.Windows	`@electron-forge/maker-squirrel`	Windows	`.exe` （支持自动更新）
WiX MSI	`@electron-forge/maker-wix`	Windows	`.msi`
MSIX	`@electron-forge/maker-msix`	Windows	`.msix`
AppX	`@electron-forge/maker-appx`	Windows	`.appx` （适用于微软商店）
DMG	`@electron-forge/maker-dmg`	macOS	`.dmg`
PKG	`@electron-forge/maker-pkg`	macOS	`.pkg` （适用于 Mac App Store）
ZIP	`@electron-forge/maker-zip`	macOS, Linux	`.zip`
deb	`@electron-forge/maker-deb`	Linux	`.deb` （适用于 Debian/Ubuntu）
RPM	`@electron-forge/maker-rpm`	Linux	`.rpm` （适用于 Fedora/RHEL）
Flatpak	`@electron-forge/maker-flatpak`	Linux	`.flatpak`
Snap	`@electron-forge/maker-snap`	Linux	`.snap`

推荐初始组合： Squirrel（Windows）+ DMG + ZIP（macOS）+ deb（Linux）。

生成器配置示例请查看 examples/core.md。

Pattern 3: Code Signing

模式 3：代码签名

macOS and Windows both require code signing for distribution. Without it, OS security warnings block or discourage installation.

macOS 和 Windows 分发均需要代码签名。否则，操作系统安全警告会拦截或阻止用户安装。

macOS (Sign + Notarize)

macOS（签名 + 公证）

typescript

packagerConfig: {
  osxSign: {},  // empty object activates defaults -- signs with first valid identity
  osxNotarize: {
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_PASSWORD,  // app-specific password, NOT Apple ID password
    teamId: process.env.APPLE_TEAM_ID,
  },
},

Requirements: Apple Developer Program membership, "Developer ID Application" certificate in Keychain,

hardenedRuntime: true

(required for notarization).

typescript

packagerConfig: {
  osxSign: {},  // 空对象启用默认配置——使用第一个有效身份签名
  osxNotarize: {
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_PASSWORD,  // 应用专用密码，而非 Apple ID 密码
    teamId: process.env.APPLE_TEAM_ID,
  },
},

要求： Apple 开发者计划会员资格、钥匙串中的“开发者 ID 应用”证书、

hardenedRuntime: true

（公证必需）。

Windows (Authenticode)

Windows（Authenticode）

typescript

// Squirrel maker with traditional certificate
{
  name: "@electron-forge/maker-squirrel",
  config: {
    certificateFile: process.env.WIN_CSC_LINK,
    certificatePassword: process.env.WIN_CSC_KEY_PASSWORD,
  },
},

Key point: Since June 2023, private keys for code signing certificates must be stored on FIPS 140 Level 2 hardware. Azure Trusted Signing is the modern alternative for Windows -- see examples/signing.md.

See examples/signing.md for full signing configuration, notarization strategies, and Azure Trusted Signing setup.

typescript

// 使用传统证书的 Squirrel 生成器
{
  name: "@electron-forge/maker-squirrel",
  config: {
    certificateFile: process.env.WIN_CSC_LINK,
    certificatePassword: process.env.WIN_CSC_KEY_PASSWORD,
  },
},

关键点： 自 2023 年 6 月起，代码签名证书的私钥必须存储在符合 FIPS 140 Level 2 标准的硬件中。Azure Trusted Signing 是 Windows 平台的现代替代方案——请查看 examples/signing.md。

完整签名配置、公证策略和 Azure Trusted Signing 设置请查看 examples/signing.md。

Pattern 4: Fuses Plugin (Binary Hardening)

模式 4：Fuses 插件（二进制加固）

Fuses are bits in the Electron binary flipped at package time to enable/disable features permanently.

typescript

import { FusesPlugin } from "@electron-forge/plugin-fuses";
import { FuseV1Options, FuseVersion } from "@electron/fuses";

plugins: [
  new FusesPlugin({
    version: FuseVersion.V1,
    [FuseV1Options.RunAsNode]: false,
    [FuseV1Options.EnableCookieEncryption]: true,
    [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
    [FuseV1Options.EnableNodeCliInspectArguments]: false,
    [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
    [FuseV1Options.OnlyLoadAppFromAsar]: true,
    [FuseV1Options.GrantFileProtocolExtraPrivileges]: false,
  }),
],

Why critical: Without

RunAsNode: false

, attackers can set

ELECTRON_RUN_AS_NODE=1

and run arbitrary code. Without

OnlyLoadAppFromAsar: true

, ASAR integrity validation can be bypassed by placing files alongside the archive.

Verification:

npx @electron/fuses read --app /path/to/packaged/app

See examples/core.md for the full fuses configuration with explanations.

Fuses 是 Electron 二进制文件中的比特位，可在打包时翻转以永久启用/禁用功能。

typescript

import { FusesPlugin } from "@electron-forge/plugin-fuses";
import { FuseV1Options, FuseVersion } from "@electron/fuses";

plugins: [
  new FusesPlugin({
    version: FuseVersion.V1,
    [FuseV1Options.RunAsNode]: false,
    [FuseV1Options.EnableCookieEncryption]: true,
    [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
    [FuseV1Options.EnableNodeCliInspectArguments]: false,
    [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
    [FuseV1Options.OnlyLoadAppFromAsar]: true,
    [FuseV1Options.GrantFileProtocolExtraPrivileges]: false,
  }),
],

为何至关重要： 若不设置

RunAsNode: false

，攻击者可通过设置

ELECTRON_RUN_AS_NODE=1

运行任意代码。若不设置

OnlyLoadAppFromAsar: true

，攻击者可通过在归档文件旁放置文件绕过 ASAR 完整性校验。

验证方式：

npx @electron/fuses read --app /path/to/packaged/app

带详细说明的完整 Fuses 配置请查看 examples/core.md。

Pattern 5: Publishers

模式 5：发布器

Publishers upload make artifacts to distribution targets.

typescript

publishers: [
  {
    name: "@electron-forge/publisher-github",
    config: {
      repository: { owner: "my-org", name: "my-app" },
      prerelease: true,
    },
  },
],

Publisher	Package	Target
GitHub	`@electron-forge/publisher-github`	GitHub Releases
S3	`@electron-forge/publisher-s3`	Amazon S3 bucket
Snapcraft	`@electron-forge/publisher-snapcraft`	Snap Store
GCS	`@electron-forge/publisher-gcs`	Google Cloud Storage

Authentication: Use

GITHUB_TOKEN

env var for GitHub publisher. Use AWS credentials (env vars or shared credentials file) for S3.

See examples/publishers.md for publisher configuration with CI/CD integration.

发布器将生成的产物上传到分发目标。

typescript

publishers: [
  {
    name: "@electron-forge/publisher-github",
    config: {
      repository: { owner: "my-org", name: "my-app" },
      prerelease: true,
    },
  },
],

发布器	包名	分发目标
GitHub	`@electron-forge/publisher-github`	GitHub Releases
S3	`@electron-forge/publisher-s3`	Amazon S3 存储桶
Snapcraft	`@electron-forge/publisher-snapcraft`	Snap Store
GCS	`@electron-forge/publisher-gcs`	Google Cloud Storage

身份验证： GitHub 发布器使用

GITHUB_TOKEN

环境变量。S3 使用 AWS 凭证（环境变量或共享凭证文件）。

带 CI/CD 集成的发布器配置请查看 examples/publishers.md。

Pattern 6: Build Hooks

模式 6：构建钩子

Hooks insert custom logic at specific points in the build lifecycle.

typescript

hooks: {
  prePackage: async (config, platform, arch) => {
    // Run before @electron/packager -- generate assets, validate config
  },
  postMake: async (config, makeResults) => {
    // Run after all makers -- rename artifacts, upload to CDN, notify
    // Return modified makeResults array to affect subsequent steps
    return makeResults;
  },
},

Hook	When	Can Mutate?
`generateAssets`	Before start or package	No
`prePackage`	Before @electron/packager	No
`packageAfterCopy`	After packager copies build dir	No
`packageAfterPrune`	After devDependencies pruned	No
`postPackage`	After package completes	No
`preMake`	Before makers run	No
`postMake`	After makers complete	Yes -- return modified `MakeResult[]`
`readPackageJson`	Every package.json read	Yes -- return modified package.json

See examples/hooks.md for hook implementation examples.

钩子可在构建生命周期的特定阶段插入自定义逻辑。

typescript

hooks: {
  prePackage: async (config, platform, arch) => {
    // 在 @electron/packager 执行前运行——生成资源、验证配置
  },
  postMake: async (config, makeResults) => {
    // 在所有生成器执行后运行——重命名产物、上传到 CDN、发送通知
    // 返回修改后的 makeResults 数组以影响后续步骤
    return makeResults;
  },
},

钩子	执行时机	是否可修改？
`generateAssets`	构建开始或打包前	否
`prePackage`	@electron/packager 执行前	否
`packageAfterCopy`	打包器复制构建目录后	否
`packageAfterPrune`	devDependencies 被清理后	否
`postPackage`	打包完成后	否
`preMake`	生成器运行前	否
`postMake`	生成器完成后	是——返回修改后的 `MakeResult[]`
`readPackageJson`	每次读取 package.json 时	是——返回修改后的 package.json

钩子实现示例请查看 examples/hooks.md。

Pattern 7: Bundler Plugins (Vite / Webpack)

模式 7：打包器插件（Vite / Webpack）

Forge plugins integrate bundlers for compiling main and renderer process code with HMR.

typescript

import { VitePlugin } from "@electron-forge/plugin-vite";

plugins: [
  new VitePlugin({
    build: [
      { entry: "src/main.ts", config: "vite.main.config.mts" },
      { entry: "src/preload.ts", config: "vite.preload.config.mts" },
    ],
    renderer: [
      { name: "main_window", config: "vite.renderer.config.mts" },
    ],
  }),
],

Status: The Vite plugin is marked experimental as of v7.5.0 -- minor versions may include breaking changes.

Key detail: The plugin injects global variables (

MAIN_WINDOW_VITE_DEV_SERVER_URL

MAIN_WINDOW_VITE_NAME

) for loading the renderer in dev vs production. Declare these in a

.d.ts

file for TypeScript.

See examples/core.md for Vite plugin setup and global variable declarations.

</patterns>

<decision_framework>

Forge 插件可集成打包器，用于编译主进程和渲染进程代码并支持热模块替换（HMR）。

typescript

import { VitePlugin } from "@electron-forge/plugin-vite";

plugins: [
  new VitePlugin({
    build: [
      { entry: "src/main.ts", config: "vite.main.config.mts" },
      { entry: "src/preload.ts", config: "vite.preload.config.mts" },
    ],
    renderer: [
      { name: "main_window", config: "vite.renderer.config.mts" },
    ],
  }),
],

状态： 截至 v7.5.0，Vite 插件标记为实验性——小版本更新可能包含破坏性变更。

关键细节： 插件会注入全局变量（

MAIN_WINDOW_VITE_DEV_SERVER_URL

、

MAIN_WINDOW_VITE_NAME

），用于在开发环境和生产环境加载渲染进程。需在

.d.ts

文件中声明这些变量以支持 TypeScript。

Vite 插件设置和全局变量声明请查看 examples/core.md。

</patterns>

<decision_framework>

Decision Framework

决策框架

Forge vs electron-builder

Choosing a build tool?
+-- Want first-party Electron support (ASAR integrity, universal macOS)?
|   +-- YES --> Electron Forge (receives features same-day as Electron)
+-- Need YAML-based config, NSIS installer, or broad community support?
|   +-- YES --> electron-builder (more installer targets, larger community)
+-- Need maximum customization for enterprise?
|   +-- YES --> electron-builder (more config options, NSIS scripting)
+-- Starting a new project?
    +-- YES --> Electron Forge (official recommendation, TypeScript config)

Factor	Electron Forge	electron-builder
Maintainer	Electron team	Community
Config format	TypeScript / JavaScript	YAML / JSON / JS
New Electron features	Same-day	Delayed
Plugin ecosystem	Makers, publishers, plugins	Built-in monolith
Windows installers	Squirrel, WiX, MSIX, AppX	NSIS, Squirrel, MSI, AppX
macOS installers	DMG, ZIP, PKG	DMG, ZIP, PKG, MAS
npm downloads	~50K/week	~1.4M/week
Architecture	Composable packages	Monolithic

选择构建工具？
+-- 需要官方 Electron 支持（ASAR 完整性、macOS 通用构建）？
|   +-- 是 --> Electron Forge（与 Electron 同步获取新功能）
+-- 需要基于 YAML 的配置、NSIS 安装程序或广泛的社区支持？
|   +-- 是 --> electron-builder（支持更多安装程序格式，社区规模更大）
+-- 需要面向企业的最大程度自定义？
|   +-- 是 --> electron-builder（更多配置选项，支持 NSIS 脚本）
+-- 启动新项目？
    +-- 是 --> Electron Forge（官方推荐，TypeScript 配置）

对比项	Electron Forge	electron-builder
维护方	Electron 团队	社区
配置格式	TypeScript / JavaScript	YAML / JSON / JS
Electron 新功能支持	同步更新	延迟支持
插件生态	生成器、发布器、插件独立分发	内置单体式架构
Windows 安装程序	Squirrel、WiX、MSIX、AppX	NSIS、Squirrel、MSI、AppX
macOS 安装程序	DMG、ZIP、PKG	DMG、ZIP、PKG、MAS
npm 周下载量	~5万	~140万
架构	可组合包结构	单体式架构

Maker Selection

生成器选择

Which maker for your platform?
+-- Windows?
|   +-- Auto-updating desktop app --> Squirrel.Windows
|   +-- Enterprise/IT deployment --> WiX MSI
|   +-- Microsoft Store --> AppX or MSIX
+-- macOS?
|   +-- Direct distribution --> DMG (drag-to-install) + ZIP (for auto-updater)
|   +-- Mac App Store --> PKG
+-- Linux?
|   +-- Debian/Ubuntu --> deb
|   +-- Fedora/RHEL --> RPM
|   +-- Universal sandboxed --> Flatpak or Snap

</decision_framework>

Detailed resources:

examples/core.md -- forge.config.ts setup, makers, Vite plugin, fuses, dependency management
examples/signing.md -- macOS notarization, Windows Authenticode, Azure Trusted Signing, entitlements
examples/publishers.md -- GitHub, S3, Snapcraft publishers with CI/CD patterns
examples/hooks.md -- Build lifecycle hooks, custom makers, extending Forge
reference.md -- Maker/publisher quick-reference tables, fuse options, CLI commands, Forge vs builder comparison

<red_flags>

为你的平台选择哪种生成器？
+-- Windows？
|   +-- 支持自动更新的桌面应用 --> Squirrel.Windows
|   +-- 企业/IT 部署 --> WiX MSI
|   +-- 微软商店 --> AppX 或 MSIX
+-- macOS？
|   +-- 直接分发 --> DMG（拖拽安装） + ZIP（用于自动更新）
|   +-- Mac App Store --> PKG
+-- Linux？
|   +-- Debian/Ubuntu --> deb
|   +-- Fedora/RHEL --> RPM
|   +-- 通用沙箱化应用 --> Flatpak 或 Snap

</decision_framework>

详细资源：

examples/core.md -- forge.config.ts 设置、生成器、Vite 插件、Fuses、依赖管理
examples/signing.md -- macOS 公证、Windows Authenticode、Azure Trusted Signing、权限配置
examples/publishers.md -- GitHub、S3、Snapcraft 发布器及 CI/CD 模式
examples/hooks.md -- 构建生命周期钩子、自定义生成器、扩展 Forge
reference.md -- 生成器/发布器速查表、Fuse 选项、CLI 命令、Forge 与 builder 对比

<red_flags>

RED FLAGS

警示事项

Critical Issues:

Placing
```
electron
```
in
```
dependencies
```
instead of
```
devDependencies
```
-- bloats the packaged app by ~200MB because Forge already provides the binary
Shipping without code signing -- macOS Gatekeeper blocks unsigned apps entirely; Windows SmartScreen shows scary warnings
Hardcoding signing credentials in
```
forge.config.ts
```
-- secrets end up in version control; always use
```
process.env
```
Not enabling ASAR (
```
asar: false
```
) -- ships your source code as readable plain-text files
Not setting
```
RunAsNode: false
```
fuse -- allows
```
ELECTRON_RUN_AS_NODE=1
```
to execute arbitrary code with your app's permissions

Architecture Issues:

Running
```
electron-forge make
```
on macOS expecting Windows .exe output -- makers run only on the target OS (use CI/CD with per-platform runners)
Placing native modules (better-sqlite3, sharp) inside ASAR without
```
asarUnpack
```
-- native addons cannot load from inside an ASAR archive
Not running
```
@electron/rebuild
```
for native modules -- modules compiled for system Node.js crash in Electron's Node.js runtime (Forge runs rebuild automatically during package, but manual installs need it)
Using
```
electron-forge package
```
for distribution -- this produces an uninstallable app bundle; use
```
make
```
for distributable installers

Configuration Mistakes:

Setting
```
asar: true
```
without
```
asarUnpack
```
for native modules -- the app will crash at runtime trying to load the native addon
Forgetting the
```
platforms
```
array on makers -- maker runs on all platforms and fails on unsupported ones
Using
```
osxNotarize
```
without
```
osxSign
```
-- notarization requires a signed binary; Apple rejects unsigned submissions
Using your Apple ID password instead of an app-specific password for
```
osxNotarize
```
-- regular passwords are rejected when 2FA is enabled

Gotchas & Edge Cases:

```
electron-forge start
```
in dev mode does not run makers -- dev mode uses unpackaged source; always test with
```
make
```
before release
Notarization takes 2-10 minutes per build -- factor this into CI/CD timeout settings
Squirrel.Windows handles first-run events (shortcuts, desktop icons) -- your main process must handle Squirrel startup events or the app opens multiple times during install
```
__dirname
```
resolves to virtual ASAR paths in packaged builds -- use
```
app.isPackaged
```
+
```
process.resourcesPath
```
for resource file paths
The Vite plugin is experimental since v7.5.0 -- minor version bumps may include breaking changes to its config shape
Azure Trusted Signing paths must not contain spaces -- signing fails silently if any path has spaces
Forge hooks run in parallel, not sequentially -- do not rely on execution order between hooks of the same type

</red_flags>

<critical_reminders>

严重问题：

将
```
electron
```
放在
```
dependencies
```
而非
```
devDependencies
```
中——Forge 已提供二进制文件，此举会使打包后的应用体积膨胀约 200MB
未签名就发布应用——macOS Gatekeeper 会完全拦截未签名应用；Windows SmartScreen 会显示警告
在
```
forge.config.ts
```
中硬编码签名凭证——密钥会被提交到版本控制；务必使用
```
process.env
```
未启用 ASAR（
```
asar: false
```
）——源代码会以明文文件形式交付
未设置
```
RunAsNode: false
```
Fuse——攻击者可通过
```
ELECTRON_RUN_AS_NODE=1
```
以应用权限执行任意代码

架构问题：

在 macOS 上运行
```
electron-forge make
```
期望生成 Windows .exe 文件——生成器仅在目标操作系统运行（需使用带对应平台运行器的 CI/CD）
将原生模块（better-sqlite3、sharp）放在 ASAR 中却未配置
```
asarUnpack
```
——原生插件无法从 ASAR 归档中加载
未为原生模块运行
```
@electron/rebuild
```
——为系统 Node.js 编译的模块在 Electron 的 Node.js 运行时会崩溃（Forge 会在打包期间自动运行 rebuild，但手动安装时需自行执行）
使用
```
electron-forge package
```
进行分发——此命令生成的是不可安装的应用包；需使用
```
make
```
生成可分发的安装程序

配置错误：

设置
```
asar: true
```
却未为原生模块配置
```
asarUnpack
```
——应用运行时会因无法加载原生插件而崩溃
生成器未设置
```
platforms
```
数组——生成器会在所有平台运行并在不支持的平台失败
使用
```
osxNotarize
```
却未配置
```
osxSign
```
——公证需要已签名的二进制文件；Apple 会拒绝未签名的提交
为
```
osxNotarize
```
使用 Apple ID 密码而非应用专用密码——启用双因素认证后，普通密码会被拒绝

陷阱与边缘情况：

开发模式下的
```
electron-forge start
```
不会运行生成器——开发模式使用未打包的源码；发布前务必用
```
make
```
测试
公证每个构建需耗时 2-10 分钟——需将此时间纳入 CI/CD 超时设置
Squirrel.Windows 处理首次运行事件（快捷方式、桌面图标）——主进程必须处理 Squirrel 启动事件，否则安装时应用会多次打开
打包后的构建中
```
__dirname
```
解析为虚拟 ASAR 路径——需结合
```
app.isPackaged
```
+
```
process.resourcesPath
```
获取资源文件路径
截至 v7.5.0，Vite 插件处于实验性阶段——小版本更新可能会修改其配置结构
Azure Trusted Signing 的路径不能包含空格——若路径含空格，签名会静默失败
Forge 钩子并行运行，而非顺序执行——请勿依赖同类型钩子的执行顺序

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

重要提醒

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type
, named constants)

(You MUST place
electron
in
devDependencies
-- Forge provides the Electron binary during packaging; placing it in
dependencies
bloats the app by ~200MB)

(You MUST code-sign macOS builds with
osxSign
and
osxNotarize
in
packagerConfig
-- unsigned apps are blocked by Gatekeeper on macOS 10.15+)

(You MUST enable
asar: true
in
packagerConfig
-- without ASAR, your source code ships as plain-text files readable by any user)

(You MUST store signing credentials in environment variables -- never hardcode secrets in
forge.config.ts
)

(You MUST enable Fuses (
FuseV1Options.RunAsNode: false
,
OnlyLoadAppFromAsar: true
) for production security -- without them, attackers can bypass ASAR integrity and run arbitrary Node.js code)

Failure to follow these rules will produce insecure, bloated, or unsigned builds that OS security mechanisms will block or warn users about.

</critical_reminders>

所有代码必须遵循 CLAUDE.md 中的项目规范（短横线命名法、命名导出、导入顺序、
import type
、命名常量）

（必须将
electron
放在
devDependencies
中——Forge 在打包期间会提供 Electron 二进制文件；若放在
dependencies
中，应用体积会膨胀约 200MB）

（必须在
packagerConfig
中配置
osxSign
和
osxNotarize
对 macOS 构建进行代码签名——未签名的应用会被 macOS 10.15+ 的 Gatekeeper 拦截）

（必须在
packagerConfig
中启用
asar: true
——若不启用 ASAR，源代码会以明文文件形式交付，任何用户都可读取）

（必须将签名凭证存储在环境变量中——切勿在
forge.config.ts
中硬编码密钥）

不遵守这些规则会生成不安全、体积过大或未签名的构建，会被操作系统安全机制拦截或向用户发出警告。

</critical_reminders>