当前位置：首页 > news >正文

Electron Forge | 跨平台实战详解(中)

news 2025/12/15 8:02:36

简介

上篇介绍了 Electron 和 Electron Builder 的基本用法，本篇将介绍更常用也更方便的打包工具，Electron Forge 。
Electron Forge 是一个为 Electron 应用的开发、打包和分发而设计的全功能工具集。它整合了多个底层 Electron 工具到一个统一的命令行界面中，极大简化开发和部署流程。

参考文档：

官方文档 – Electron Forge
打包教程 – Packaging Your Application

准备工作

首先，将项目环境重置为 Vue 的开发环境。或者创建一个新项目：

npm create vite@latest electron-demo

加入 Electron 依赖，这部分上篇已经详细介绍，主要步骤包括：安装依赖，添加 main.js 和 preload.js 文件，修改 package.json 文件，支持 electron 热更新开发，只是去掉了最后的 electron-builder 的配置。

安装依赖

安装 @electron-forge/cli

npm install --save-dev @electron-forge/cli

用 npx electron-forge import 命令将现有的 Electron 项目转换为 Electron Forge 项目。这一步会自动生成 forge.config.js 配置文件。

npx electron-forge import

安装额外依赖，根据目标平台，安装相应的打包工具（makers）。

# 可以写成一行，这里分开写方便理解
npm install --save-dev electron-squirrel-startup
npm install --save-dev @electron-forge/maker-squirrel 
npm install --save-dev @electron-forge/maker-deb 
npm install --save-dev @electron-forge/maker-rpm
npm install --save-dev @electron-forge/maker-zip
npm install --save-dev @electron-forge/maker-dmg

支持的应用列表

这些依赖的用处如下，根据需要，选择合适的打包工具（maker），参考 Maker 文档：

包名	后缀	说明
`electron-squirrel-startup`	N/A	管理 Windows 平台下的 Squirrel 安装过程
`@electron-forge/maker-squirrel`	`.exe`	Windows 的 Squirrel 安装包
`@electron-forge/maker-deb`	`.deb`	Debian-based Linux 系统的 DEB 包
`@electron-forge/maker-rpm`	`.rpm`	RPM-based Linux 系统的 RPM 包
`@electron-forge/maker-zip`	`.zip`	为各平台创建 ZIP 压缩包
`@electron-forge/maker-dmg`	`.dmg`	macOS 的 DMG 镜像文件
`@electron-forge/maker-flatpak`	`.flatpak`	Linux 的 Flatpak 包
`@electron-forge/maker-snap`	`.snap`	Linux 的 Snapcraft 包
`@electron-forge/maker-appx`	`.appx`	Windows Store 的 AppX 安装程序

注意，跨平台的构建通常还要安装拓展的包：

DMG 文件只能在 macOS 计算机上构建
在 Mac 上构建 Windows 的安装包，需安装 wine 和 mono
在 Mac 上构建 Linux 的安装包，需安装 dpkg, fakeroot

修改配置

维护元数据，在 package.json 文件中更新 author 和 description 字段，帮助用户和其他开发者了解项目的基本信息。而且 Windows 平台的构建，这两个参数是必填的。

默认环境打包

简单地运行以下命令：

npm run build
npm run make # npx electron-forge make

electron-forge make 命令背后包含了两个步骤：

在后台执行 electron-forge package，将应用代码与 Electron 二进制文件捆绑在一起。打包后的代码会被输出到一个文件夹中。
使用该文件夹为每个配置的创建一个单独的可分发文件。

mac 系统下，产出的文件结构：

out
├── electron-demo-darwin-arm64
│   ├── LICENSE
│   ├── LICENSES.chromium.html
│   ├── electron-demo.app
│   └── version
└── make└── zip└── darwin└── arm64└── electron-demo-darwin-arm64-0.0.0.zip5 directories, 3 files

如果只构建一个平台，可将 npm run build 写在 npm run make 里，一键完成构建。但如果要打包多个平台，则建议分开，npm run build 命令只需执行一次。

支持的架构列表

Make 参数文档：https://www.electronforge.io/cli#make

在 forge.config.js 中为不同的平台配置特定的打包工具（maker）。例如，以下配置为 macOS 和 Linux 平台创建 ZIP 压缩包：

module.exports = {makers: [{name: '@electron-forge/maker-zip',platforms: ['darwin', 'linux'],config: {// 特定配置}}]
};

支持的配置选项如下：

参数	取值	描述
`--arch`	如 x64	目标架构。默认为您当前的架构（"host"架构）。允许的值包括：“ia32”, “x64”, “armv7l”, “arm64”, “universal”, 或 “mips64el”。如果有多个值，应用逗号分隔。
`--platform`	如 mas	目标平台。通常，您只能在平台 X 上为平台 X 制作包。默认为您正在运行的平台（"host"平台）。
`--targets`	制作目标的逗号分隔列表	为此次运行覆盖制作目标。制作工具名是完整的 node 模块名，如 `@electron-forge/maker-deb`。默认情况下，使用的制作目标是为给定平台配置和可用的目标。
`--skip-package`	N/A	如果您希望跳过打包步骤，可设置此选项，特别是在连续执行多次打包时可以节省时间。默认不跳过打包。

基本用法示例：

# 默认情况下，make 命令对应一个 npm 脚本：
npm run make -- --arch="ia32"

设置应用图标

参考文档: Custom App Icons

为 Electron 应用设置专业的图标，需要按照特定的格式和大小标准进行创建。以下是每个操作系统推荐的文件格式和图标大小：

操作系统	格式	大小
macOS	`.icns`	512x512 像素（视网膜显示屏为 1024x1024）
Windows	`.ico`	256x256 像素
Linux	`.png`	512x512 像素

对于 Windows 和 macOS，可以在 forge.config.js 中配置图标路径。由于 Electron Forge 会自动为每个平台添加正确的扩展名，因此无需在路径中包含 .ico 或 .icns 后缀。

module.exports = {// 其他配置...packagerConfig: {icon: '/path/to/icon' // 路径中不包括文件扩展名}// 其他配置...
};

可以用相对 forge.config.js 文件的路径，或者绝对路径。可以省略扩展名，以同时支持多个平台。

对于 Linux，配置图标的路径则需要在 forge.config.js 中指定：

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

同时，在实例化 BrowserWindow 时，也需要指定图标：

// main.js
const { BrowserWindow } = require('electron')const win = new BrowserWindow({// 其他配置...icon: '/path/to/icon.png'
});

此外，安装程序的图标配置可以单独配置，详见文档。

附：图标转化工具

Windows 的 .ico 文件可直接用 ImageMagick 转换：

# 安装 ImageMagick
# brew install imagemagick # macOS
# sudo apt-get install imagemagick # Ubuntu
convert avatar.png output.ico
convert avatar.png -define icon:auto-resize="256,128,64,48,32,16" output.icns

macOS 的 .icns 可以用 png2icns 来转化：

npm install png2icns -g
png2icns /path/to/icon.png -s 16,32,64,128,256

但实测部分图标会转化失败。可以手写脚本，基于系统自带的 sips 和 iconutil 工具来转换图标：

#!/bin/bash# 检查参数是否传入及图片文件是否存在
if [ "$#" -lt 1 ] || [ ! -f "$1" ]; thenecho "用法: $0 <图片路径> [最大尺寸]"exit 1
fiPIC_FILE=$1
MAX_SIZE=${2-1024} # 设置默认最大尺寸为1024# 检查 sips 和 iconutil 命令是否存在
if ! command -v sips &> /dev/null || ! command -v iconutil &> /dev/null; thenecho "sips 或 iconutil 工具不存在。脚本需要在 macOS 上运行。"exit 1
fi# 转换图片到不同的尺寸并创建 icns 文件
mkdir -p tmp.iconset &&for sz in 16 32 64 128 256 512 1024; do if [ $sz -le $MAX_SIZE ]; thensips -z $sz $sz "$PIC_FILE" --out tmp.iconset/icon_${sz}x${sz}.pngfiif [ $sz -ge 32 ] && [ $(($sz * 2)) -le $MAX_SIZE ]; thensips -z $(($sz * 2)) $(($sz * 2)) "$PIC_FILE" --out tmp.iconset/icon_${sz}x${sz}@2x.pngfidone &&iconutil -c icns tmp.iconset -o Icon.icns && rm -r tmp.iconset

不同平台的打包实战

macOS 平台

针对 macOS 平台，需要分别考虑 ARM 和 Intel 架构。以下命令将分别为这两种架构生成安装包：

# 为 macOS Intel 架构打包
npx electron-forge make --platform=darwin --arch=x64 --targets="@electron-forge/maker-dmg" --icon=public/rex# 为 macOS ARM 架构打包
npx electron-forge make --platform=darwin --arch=arm64 --targets="@electron-forge/maker-dmg" --icon=public/rex# 为 macOS ARM 架构打包 | 输出 .app 可执行文件
npx electron-forge make --platform=darwin --arch=arm64 --targets="@electron-forge/maker-zip" --icon=public/rex

Windows 平台打包

Windows 7 和 Windows 10 系统，可以使用以下命令进行打包：

# 打包为 Windows 安装程序 (x64)
npx electron-forge make --platform=win32 --arch=x64 --targets="@electron-forge/maker-squirrel" --icon=public/rex# 打包为 Windows 安装程序 (x86)
npx electron-forge make --platform=win32 --arch=ia32 --targets="@electron-forge/maker-squirrel" --icon=public/rex

Ubuntu Linux 平台打包

对于 Ubuntu Linux，我们将打包为 .deb 格式，适用于基于 Debian 的系统：

# 打包为 Ubuntu .deb 包
npx electron-forge make --platform=linux --arch=x64 --targets="@electron-forge/maker-deb" --icon=public/rex

小结

以上，根据不同的操作系统和架构需求，为 Electron 应用创建安装包。更详细的配置和参数设置，可参考 Electron Forge 文档。

到这里，我们已经能在本地针对不同平台打包应用。

下一篇我们将介绍如何利用 GitHub Actions 自动化构建和发布 Electron 应用。GitHub Actions 是一个强大的自动化工具，用于自动执行构建、测试和部署等多种操作。

简介