企业官网建设流程全解析

• 开发工具
• 桌面应用
• 前端构建

在 Electron Forge 中，应用图标贯穿「打包产物」与「各平台安装包」两个层面：前者通过packagerConfig.icon控制可执行文件/App 的图标，后者通过对应 Maker 的config控制 DMG、Deb、Squirrel、Wix 等安装程序界面中的图标。本文以仓库中的官方指南 docs/guides/create-and-add-icons.md 为主线，结合 maker 源码与配置类型定义，系统讲解从 1024x1024 源图出发，如何生成各平台所需格式（.icns/.ico/.png/ Icon Composer.icon）、如何处理高 DPI 密度、如何分别配置应用图标与安装程序图标，并给出 Windows 图标缓存刷新的排障方案。读完本文，你将能为一套 Electron 项目完整配置 macOS、Windows、Linux 三平台的应用与安装包图标。

第一步：生成各平台所需的图标文件

Electron 的打包与安装流程不会自动把一张图片转换成平台所需格式，因此你需要先为每个目标平台准备好符合格式与尺寸要求的图标文件。推荐使用网络上各类在线转换工具完成格式转换，起点统一使用一张1024x1024px的高质量源图——这个尺寸可以无损缩放到各平台要求的分辨率，也能满足 Apple Retina 等高分屏的@2x需求。

支持高分屏：使用 @2x 密度后缀

在支持高 DPI 的平台（如 Apple Retina 显示屏）上，可以在图片基础文件名后追加@2x后缀，将其标记为高分辨率图：若icon.png是标准分辨率图片，则icon@2x.png会被视为 DPI 强度翻倍的高分辨率图。

如果你想在同一目录中同时支持多种 DPI 密度的显示设备，可以把不同尺寸的图片放在同一个文件夹，并使用「不带 DPI 后缀」的基础文件名，Electron 会自动按密度匹配。官方推荐的目录结构如下：

images/ ├── icon.png ├── icon@2x.png └── icon@3x.png

除@2x外，Electron 还支持以下全部 DPI 后缀，可覆盖从 1x 到 5x 的主流屏幕密度：

@1x、@1.25x、@1.33x、@1.4x、@1.5x、@1.8x、@2x、@2.5x、@3x、@4x、@5x

各平台推荐的格式与尺寸

不同操作系统对图标的封装格式和像素尺寸要求差异很大，官方推荐如下：

两个容易踩的坑

1. Windows 的.ico必须由支持该格式的图像编辑器导出（例如 GIMP 等），绝不能把.png直接重命名成.ico——否则打包时 Electron Packager 会抛出Fatal error: Unable to set icon错误。.ico内部包含多分辨率帧及位深信息，重命名只会得到一张无效的伪 ICO。
2. macOS 的 Icon Composer.icon文件属于较新的能力：@electron/packager从 v18.4.0 起支持 macOS Icon Composer 文件。若需要同时兼容 macOS 26+ 与更早版本，应同时提供.icns和.icon两个文件（后文会说明如何在配置中同时指定）。

第二步：在 Forge 配置中设置应用图标

应用图标（打包后 App / 可执行文件的图标）统一通过packagerConfig.icon配置，但 Windows、macOS、Linux 三者的具体写法和生效路径并不相同。

Windows：单个 icon 路径，无需写扩展名

在 forge.config.js 中配置packagerConfig.icon即可：

module.exports = { // ... packagerConfig: { icon: '/path/to/icon' // no file extension required } // ... };

提示：当只提供一个 icon 路径时，Electron Packager 会自动补上对应平台的扩展名（Windows 下推断为.ico），所以这里无需手动追加.ico。

配置更新后，运行 Make 命令构建项目，即可生成带图标的应用产物（npx electron-forge make或npm run make）。

macOS：单 .icns 或双文件兼容方案

如果只需要传统 macOS 图标格式，沿用单个icon路径即可，Packager 会自动推断.icns扩展名：

module.exports = { // ... packagerConfig: { icon: '/path/to/icon' // .icns will be inferred } // ... };

如果需要一套配置同时兼容 macOS 26+ 和更早版本，则同时提供.icns与.icon两个文件，并写成数组形式：

module.exports = { // ... packagerConfig: { icon: [ '/path/to/icon.icns', '/path/to/icon.icon' ] } // ... };

此时 Electron Packager 会在 macOS 26 之前的系统上使用.icns文件，在 macOS 26 及之后的系统上使用.icon文件。

使用.icon文件需要特别注意两个前提条件：

• 打包.icon文件目前要求 macOS 26 或更高版本、Xcode 26 或更高版本，因为 Electron Packager 需要调用 Apple 的actool工具来编译 Icon Composer 资源；
• 同时提供多个 macOS 图标文件时，必须显式写出文件扩展名（即写成icon.icns、icon.icon而不是裸文件名icon），否则 Packager 无法区分.icns与.icon两个输入。

配置完成后，同样通过 Make 命令构建项目。

Linux：双重配置，两处都要设置

Linux 的图标配置是三大平台中最特殊的一个：既要在 Forge 配置（对应 maker-deb 打包进安装包），又要在 Electron 主进程中设置（对应运行时的窗口图标）。

首先在makers中为@electron-forge/maker-deb配置图标：

module.exports = { // ... makers: [ { name: '@electron-forge/maker-deb', config: { options: { icon: '/path/to/icon.png' } } } ] // ... };

同时在主进程实例化 BrowserWindow 时加载同一个图标：

const { BrowserWindow } = require('electron'); const win = new BrowserWindow({ // ... icon: '/path/to/icon.png' });

从源码看，icon正是@electron-forge/maker-deb配置类型中options里的一个显式字段，其类型注释为 "Path to a single image that will act as icon for the application"（见 packages/maker/deb/src/Config.ts）；而 MakerDeb.make() 会通过{ options: {}, ...this.config, ... }把这段配置原样透传给底层electron-installer-debian，最终写入.deb包内 desktop 文件的Icon字段。因此这里要求的是单张图片的路径（Linux 推荐 512x512 的.png）。

完成两处配置后，运行npm run make构建项目即可。

第三步：别忘了安装程序（Installer）图标

应用图标和安装程序图标是两回事——安装程序（Setup.exe、DMG、.deb、MSI 等）通常都有自己的图标，需要在各 Maker 的config中分别配置。官方完整示例（位于 forge.config.js 的makers段）：

// forge.config.js module.exports = { // ... makers: [ { name: '@electron-forge/maker-squirrel', config: { // An URL to an ICO file to use as the application icon (displayed in Control Panel > Programs and Features). iconUrl: 'https://url/to/icon.ico', // The ICO file to use as the icon for the generated Setup.exe setupIcon: '/path/to/icon.ico' } }, { // Path to a single image that will act as icon for the application name: '@electron-forge/maker-deb', config: { options: { icon: '/path/to/icon.png' } } }, { // Path to the icon to use for the app in the DMG window name: '@electron-forge/maker-dmg', config: { icon: '/path/to/icon.icns' } }, { name: '@electron-forge/maker-wix', config: { icon: '/path/to/icon.ico' } } ] // ... };

各 Maker 的配置项含义与底层来源如下：

• @electron-forge/maker-squirrel（Windows Setup.exe / nupkg）
  • iconUrl：应用图标的 URL，用于显示在「控制面板 > 程序和功能」中；
  • setupIcon：生成的Setup.exe使用的 ICO 文件路径。
  • 从源码看，MakerSquirrel 的配置类型直接继承electron-winstaller的Options（见 packages/maker/squirrel/src/MakerSquirrel.ts），并在make()中通过{ ...this.config, ... }合并透传给createWindowsInstaller（见 MakerSquirrel.make()），因此这两个字段即electron-winstaller的原生选项。
• @electron-forge/maker-deb（Debian/Ubuntu.deb）
  • options.icon：打包进.deb的应用图标，单张图片路径（推荐.png），字段定义见 packages/maker/deb/src/Config.ts。
• @electron-forge/maker-dmg（macOS 磁盘映像）
  • icon：DMG 窗口内显示的 app 图标路径，使用.icns。MakerDMG 的配置类型继承自electron-installer-dmg的ElectronInstallerDMGOptions（见 packages/maker/dmg/src/Config.ts），其单测也验证了配置与createDMG调用之间的透传关系（见 packages/maker/dmg/spec/MakerDMG.spec.ts）。
• @electron-forge/maker-wix（Windows MSI）
  • icon：MSI 安装程序使用的 ICO 文件。MakerWix 的配置类型继承自electron-wix-msi的MSICreatorOptions（见 packages/maker/wix/src/Config.ts），同样属于底层库的原生选项。

需要了解各 Maker 的完整配置项，可查阅仓库内的 Makers 配置文档（其中 squirrel.windows.md、deb.md、dmg.mdx、wix-msi.md 等子页分别对应各 Maker）。

完成安装程序图标配置后，同样使用 Make 命令构建项目。

故障排查：图标不更新？先刷新系统图标缓存

各操作系统都有图标缓存机制。如果修改图标后界面仍显示旧图标或默认图标，推荐先重置缓存。

Windows 刷新图标缓存

Windows 会把所有应用程序图标缓存到一个隐藏的「图标缓存数据库」中。如果 Electron 应用的图标没有正确显示，可以通过系统自带的ie4uinit.exe工具使缓存失效：

ie4uinit.exe -show

该命令会触发系统重新加载并重建图标缓存；执行后若仍不生效，通常还需重启资源管理器（任务管理器中对「Windows 资源管理器」右键选择「重新启动」）或注销再登录系统，让缓存彻底重建。macOS（lsregister/ 重建 LaunchServices 数据库）与 Linux（GTK/Qt 图标主题缓存）也有各自的图标缓存，修改图标后建议重启桌面环境或执行对应缓存清理命令确认效果。

小结：一套图标配置的最小清单

实操顺序建议：先准备 1024x1024 源图 → 按上表转换出.icns/.ico/.png（高分屏需求可补@2x系列）→ 在packagerConfig与各 Makerconfig中填写路径 → 执行npm run make生成并验证产物 → 若图标未更新则刷新系统图标缓存。

• 开发工具
• 桌面应用
• 前端构建