Electron Builder 快速配置、多平台配置与 NSIS 安装器打包策略

概述

这两节定位是快速上手版、基础认知版，而不是字段精读版。课程真正想解决的不是“把所有配置背下来”，而是让你先搞清 Builder 配置长什么样、多平台配置怎么分层、macOS / Windows / Linux 最常见目标格式分别是什么、Windows 安装器体验是怎么被配置项直接影响的。最有效的方法始终是“公共层 + 平台层”：公共层放共用信息，mac / win / linux 在其上叠加平台差异。配完之后一定要回去看产物和安装流程，建立“配置 → 产物 → 用户体验”的映射。

学习目标

• 理解 Builder 配置应按“公共层 + 平台层 + 安装器层”来拆，而非平铺硬记。
• 知道 macOS 常见 dmg、Windows 常见 nsis、Linux 常见 AppImage 的交付形态差异。
• 掌握 nsis 关键交互字段（oneClick、allowToChangeInstallationDirectory、shortcutName）。
• 建立“配置 → 产物 → 安装流程 → 用户体验”的验证闭环。
• 认识本地能打包只是开始，签名与 CI/CD 才是正式交付的下一步。

一、正确学习姿势是先跑通最小闭环

这两节的共同定位很明确：是快速上手版、基础认知版，不是完整文档精读版。课程真正想解决的问题不是“把所有配置背下来”，而是让你先搞清楚——Builder 配置长什么样、多平台配置大致怎么分层、三个平台最常见的目标格式是什么、Windows 安装器体验是怎么被配置项直接影响的、为什么真实交付不能只停留在“本地能打包”。先把最小闭环跑通，后面再补签名、自动更新和发布通道，学习成本会低很多。

type BuilderLearningStage =
  | "basic-config"
  | "platform-config"
  | "artifact-verification"
  | "signing-and-publishing"

二、公共层 + 平台层是最有效的拆法

Builder 配置最怕的读法，就是把它当成一大坨平铺字段逐个硬记。更好的理解方式是先按层次来拆：公共配置、mac、win、linux，必要时再看 nsis 这类更细的安装器配置层。最外层通常放 appId、productName、copyright、输出目录，这些对全部平台成立；而 mac、win、linux 则是在共用信息之上各自追加差异，而不是互相替代。

{
  "build": {
    "appId": "com.example.app",
    "productName": "ExampleApp",
    "mac": {},
    "win": {},
    "linux": {}
  }
}

三、多平台配置的本质是交付形态不同

Electron 桌面应用并不像 Web 那样只产出一个 dist 目录就结束。当你开始做 Builder 配置时，本质上已经进入“交付应用”的阶段，需要思考 macOS 用户拿到什么、Windows 用户拿到什么、Linux 用户拿到什么。三个平台的差异不只是字段名字不同，更是交付模型不同：macOS 常见 dmg、Windows 常见 nsis（也可额外给 zip）、Linux 常见 AppImage。多平台配置不是为了“凑齐三个对象”，而是让每个平台都以符合该平台习惯的方式交付。

{
  "build": {
    "mac": { "target": ["dmg"] },
    "win": { "target": ["nsis", "zip"] },
    "linux": { "target": ["AppImage"] }
  }
}

四、macOS 基础目标 dmg 与 category

课程在 macOS 配置里重点强调了两个字段：target: ["dmg"] 和 category。dmg 是很多 macOS 应用最常见的基础分发形态，足够适合入门阶段理解“用户最终拿到什么”。而 category 虽然看起来像元数据，但它提醒你一件很关键的事：桌面端应用不是只要打出包就完事，它还带有分发、归类、系统识别等属性。这类字段在快速配置阶段不一定要全部展开，但需要尽早建立意识。

{
  "mac": {
    "target": ["dmg"],
    "category": "public.app-category.utilities"
  }
}

五、Windows 最该掌握的是 nsis

Windows 端课程最核心的重点就是 nsis，因为对多数 Electron 项目来说，Windows 用户最熟悉的是 .exe 安装器体验，而 nsis 正是在描述这套体验。课程想让你意识到：桌面端打包不是只有产物格式，安装流程本身也是产品体验的一部分。所以 Windows 配置不应只盯着 win.target，还要继续看 nsis 配置层。一旦理解这一点，就会知道桌面端打包和前端静态资源构建的思维完全不同。

{
  "win": { "target": ["nsis", "zip"] },
  "nsis": {
    "oneClick": false,
    "allowToChangeInstallationDirectory": true
  }
}

六、oneClick / allowToChangeInstallationDirectory 定义安装体验

课程把 oneClick: false 和 allowToChangeInstallationDirectory: true 单独拿出来讲，是因为它们非常有代表性。它们并不是“语法记忆点”，而是安装体验设计点：oneClick: false 代表安装过程不是一键静默完成，allowToChangeInstallationDirectory: true 代表用户可以自己选安装位置。这会直接影响用户看到的安装步骤、是否有目录选择页、整体感受更偏“标准安装器”还是“快速安装器”。这类配置越早建立直觉越好。

type NsisInstallerExperience = {
  oneClick: boolean
  allowToChangeInstallationDirectory: boolean
  shortcutName: string
}

七、Linux 先走最少必要配置

课程对 Linux 的展开明显比 Windows 少，这并不是说 Linux 不重要，而是很多项目在初期对 Linux 端的要求通常更偏向：先有基础产物、先能运行和分发、再按真实场景细化。因此 Linux 这边常见的最小配置思路就是：目标格式、分类、可执行文件名、图标。这也说明 Builder 的多平台配置并不要求三端复杂度完全一致，可以按当前交付优先级决定先精细打磨哪一端。

{
  "linux": {
    "target": ["AppImage"],
    "category": "Utility",
    "executableName": "my-app",
    "icon": "buildResources/icon.png"
  }
}

八、配置 → 产物 → 安装流程的验证闭环

课程一个很好的实践习惯是：配完配置、马上看产物、再看安装器行为。很多字段只有落到真实产物上你才会真正理解——有没有生成预期的 dmg、.exe、.zip、AppImage，安装器有没有目录选择页，快捷方式命名是否正确，图标是否按预期显示。一旦建立这套映射，你以后再看到任意 Builder 配置，就不容易停留在抽象字段层面了。证书和 CI/CD 是下一阶段的事，但本地验证已经让你具备思考交付链路的能力。

常见问题

延伸阅读

• 上一篇：Electron 打包工具选型、Forge 与 Builder 对比及跨平台构建策略
• 下一篇：macOS 开发者证书、Electron Builder 签名与 CSC_LINK 接入
• 相关：electron-builder 官方文档、NSIS Target、Electron 代码签名