33. 打包配置与资源

上一章你跑通了 npm run make，但生成的安装包还只是「能装」。真实项目需要把图标、额外资源、原生模块都正确打包进去。这些都在 forge.config.js 里配置。本章拆解最常用的配置项，让你掌控打包的每一个细节。

本节目标

理解 asar 归档的作用与解包例外（asarUnpack）。
为不同平台配置应用图标。
用 extraResource / extraFiles 带上额外文件。
看懂 packagerConfig、makers、plugins 三大区块。
知道各平台应用入口的目录差异。

1-1 forge.config.js 的骨架

一个典型的 forge.config.js 由几个区块组成。下面是最常用的结构：

// forge.config.js（主进程/构建配置，运行在 Node 环境）
const { FusesPlugin } = require('@electron-forge/plugin-fuses');
const { FuseV1Options, FuseVersion } = require('@electron/fuses');

module.exports = {
  packagerConfig: {
    asar: true,
    icon: 'assets/icon',
    extraResource: ['./resources'],
  },
  rebuildConfig: {},
  makers: [
    {
      name: '@electron-forge/maker-squirrel',
      platforms: ['win32'],
    },
    {
      name: '@electron-forge/maker-dmg',
      platforms: ['darwin'],
    },
    {
      name: '@electron-forge/maker-deb',
      platforms: ['linux'],
    },
  ],
  plugins: [
    new FusesPlugin({
      version: FuseVersion.V1,
      [FuseV1Options.RunAsNode]: false,
      [FuseV1Options.EnableCookieEncryption]: true,
      [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
      [FuseV1Options.EnableNodeCliInspectArguments]: false,
    }),
  ],
};

packagerConfig 直接透传给定底层的 @electron/packager，控制「应用本身长什么样」。makers 决定「生成哪种安装包」。plugins 里的 FusesPlugin 用于固化 Electron 的安全开关，强烈建议保留。

1-2 asar 归档

默认情况下 Forge 会把你的源码打进一个 asar 归档。asar 是 Electron 专用的归档格式，类似只读的 zip。它有三个好处：缓解 Windows 上长路径名问题、加速 require 加载、让源码不被随手翻看。

启用方式就是在 packagerConfig 里写 asar: true。绝大多数情况保持开启即可。

但 asar 是只读的，且部分 Node API 需要真实文件路径。例如原生模块（.node 文件）、需要被 child_process.execFile 执行的二进制，都不能放在 asar 里直接运行。这时用 asarUnpack 把特定文件「解包」到外面：

// forge.config.js
module.exports = {
  packagerConfig: {
    asar: {
      unpack: '{*.node,bin/**}',
    },
  },
};

解包后的文件会出现在同级的 app.asar.unpacked 目录，需随应用一起分发。官方文档提醒：某些杀毒软件会对「临时解包」行为报警，用 asarUnpack 提前解包可规避。

1-3 应用图标

图标是用户对应用的第一印象。Forge 会根据平台自动挑选正确的图标格式，你只需在 packagerConfig.icon 指向图标文件（不带扩展名）：

packagerConfig: {
  icon: 'assets/icon',
}

把不同格式放在同一目录：icon.png（通用）、icon.icns（macOS）、icon.ico（Windows）。@electron/packager 会按平台选择。建议准备 512×512 以上的源图，避免缩放模糊。

提示：macOS 的 .icns 和 Windows 的 .ico 有各自的尺寸要求，可用 electron-icon-maker 等工具从一张 PNG 批量生成。

1-4 额外资源文件

很多应用需要随包发布非代码资源：数据库文件、证书、外部可执行程序、静态模板等。Forge 提供两个配置项。

extraResource：把文件放进 resources/ 目录，运行时应通过 process.resourcesPath 访问：

packagerConfig: {
  extraResource: ['./resources/seed.db', './resources/helper'],
}

在主进程里读取：

// main.js（主进程）
const { app } = require('electron');
const path = require('node:path');
const fs = require('node:fs');

const dbPath = path.join(process.resourcesPath, 'seed.db');
const data = fs.readFileSync(dbPath);

extraFiles：与 extraResource 类似，但放在应用根目录而非 resources/，通常用于需要贴近可执行文件的特殊文件。绝大多数场景用 extraResource 即可。

1-5 makers：各平台的安装包

makers 决定产出什么格式。常用 maker：

Windows：@electron-forge/maker-squirrel（生成 .exe 安装程序）、@electron-forge/maker-wix（MSI）。
macOS：@electron-forge/maker-dmg（.dmg 磁盘镜像）、@electron-forge/maker-zip。
Linux：@electron-forge/maker-deb（.deb）、@electron-forge/maker-rpm（.rpm）。

每个 maker 有自己的配置，例如 dmg 可指定背景图：

{
  name: '@electron-forge/maker-dmg',
  config: {
    background: 'assets/dmg-background.png',
    icon: 'assets/icon.icns',
  },
}

只在本平台运行 make 时，对应 maker 才会生效。platforms 字段限定它适用的操作系统。

1-6 各平台入口目录

打包后，应用内部目录因平台而异，理解它有助于定位资源：

macOS：MyApp.app/Contents/Resources/（你的代码与 asar 在此）。
Windows / Linux：resources/（应用根目录下的 resources 文件夹）。

这也是为什么读取额外资源要用 process.resourcesPath 而非硬编码路径——它会返回当前平台的正确位置。

1-7 安全固化插件

plugins 里的 FusesPlugin 会写入 Electron 的「fuses」开关，例如禁止应用以 Node 脚本方式运行（RunAsNode: false）、关闭可通过环境变量注入的调试入口。这能堵住一批安全隐患。官方模板默认带上，请勿删除。

1-8 跨平台配置差异

同一份配置在不同系统会有不同表现，需心中有数。icon 字段虽写一处，但各平台读各自格式；extraResource 在 macOS 落在 Resources/，在 Windows/Linux 落在 resources/，代码中必须用 process.resourcesPath 而非硬编码。

若某些配置只想对单一平台生效，可在 packagerConfig 里用 osx/win32/linux 子对象覆盖。例如只在 Windows 解包某个二进制：

// forge.config.js
module.exports = {
  packagerConfig: {
    asar: true,
    win32: {
      asar: { unpack: 'bin/win-tool.exe' },
    },
  },
};

macOS 对签名与公证有硬性要求，darwin 下若没配 osxSign，make 仍会成功但不公证，用户打开必报警。Linux 相对宽松，但进商店需对应格式。

常见误区

把原生模块直接打进 asar。.node 文件无法在 asar 内被 dlopen，必须用 asarUnpack 解包。
用相对路径读取额外资源。硬编码 ./resources 在打包后失效，应使用 process.resourcesPath。
删掉 FusesPlugin。它会固化安全开关，删除会削弱应用安全性。
忽略 .gitignore。未排除 out/ 会让仓库膨胀。

1-9 用环境变量调试打包

打包出错时，环境变量能暴露更多。DEBUG=electron-forge* 会让 Forge 打印每一步调用的底层命令，便于判断是 packager 还是 maker 阶段报错。ELECTRON_CACHE 可指定缓存目录，规避默认目录的权限问题。

若安装包体积异常大，先用 npm run package 看未压缩的应用目录，再用系统工具查看哪类文件占比高。常见元凶是误把 node_modules 全量打进、或资源目录混入大文件。定位后通过 .gitignore、.electronignore 或调整 extraResource 范围解决。验证额外资源是否到位，可在 main.js 打印 process.resourcesPath 并读目录，或用 npx asar list 查看归档内容。

1-10 图标格式细节

图标并非随便一张图。macOS 要求 .icns，里面需包含多种尺寸（16/32/64/128/256/512/1024）；Windows 的 .ico 同样是多分辨率容器。直接用单张 PNG 改名会显示模糊或失败。社区工具 electron-icon-maker 可把一张 1024 正方形 PNG 自动生成各平台所需格式，省去手工拼装。图标路径在 packagerConfig.icon 指向基名，Forge 按平台挑选对应扩展名。

1-11 快速自查清单

写完配置后，对照这份清单自查：asar 是否开启、图标是否覆盖三平台、额外资源是否用 process.resourcesPath 读取、原生模块是否已 asarUnpack、各平台 maker 是否安装、FusesPlugin 是否保留。任何一项遗漏都会在 make 或用户安装时暴露。把这些写进团队的发布前检查，能少踩很多坑。

小结

本章覆盖了 forge.config.js 的核心：asar 归档与解包、图标、额外资源、各平台 maker，以及安全固化插件。配置正确后，你的安装包就已成型。下一章讲如何让这个安装包通过系统安全校验——代码签名与公证。