Electron Forge Flatpak Maker 完全指南：构建沙箱化 Linux 应用安装包

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

导读

@electron-forge/maker-flatpak是 Electron Forge 官方提供的一个 Maker（打包器），用于把已打包的 Electron 应用生成.flatpak格式的 Linux 安装包。Flatpak 是一种面向 Linux 发行版的打包格式，它允许应用在沙箱中隔离安装、与系统其余部分相互独立地运行，与传统的 deb、RPM 等非沙箱安装方式形成鲜明对比。读完本文，你将掌握该 Maker 的安装与配置方法、全部配置项的含义与默认值、底层架构映射与构建输出结构，以及构建失败时的调试手段。

一、Flatpak 是什么，为什么用它

Flatpak 的核心价值在于"一次构建、处处运行"与安全隔离：

• 沙箱隔离：应用运行在隔离环境中，无法随意访问宿主系统的其他部分，所需权限必须通过finish-args显式授予；
• 运行时共享：应用基于org.freedesktop.Platform等共享运行时（runtime）与 SDK 构建，无需把系统库全部打入安装包；
• 跨发行版分发：同一份.flatpak文件可以在不同 Linux 发行版上安装，摆脱对发行版包管理器与依赖版本的耦合。

在 Electron Forge 的打包器生态中，deb 与 rpm 安装方式并不提供沙箱；如果目标是强隔离、跨发行版的 Linux 分发，Flatpak 是官方推荐的补充目标。从源码看，该 Maker 在 MakerFlatpak.ts 中声明defaultPlatforms: ['linux']，即默认仅在 Linux 平台生效。

二、构建环境要求

2.1 必需的三个命令行工具

只能在系统安装了以下工具后才能构建 Flatpak 目标（README 明确要求）：

这一定要求同样体现在源码中：MakerFlatpak.ts 声明了requiredExternalBinaries: string[] = ['flatpak-builder', 'eu-strip']。@electron-forge/maker-base基类会在构建前通过ensureExternalBinariesExist()（见 Maker.ts）逐一检查这些二进制是否存在，缺失时抛出错误：

Cannot make for flatpak, the following external binaries need to be installed: flatpak-builder, eu-strip

注意：源码的必检清单中是flatpak-builder与eu-strip，文档同时要求flatpak本体齐备，因为构建时拉取与复用运行时依赖flatpak。

2.2 添加 Flathub 远程仓库

构建所需的运行时来自 Flathub，需要先把远程仓库注册到当前用户（官方文档 docs/config/makers/flatpak.md 给出的命令）：

flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo

--if-not-exists保证重复执行不会报错，--user把仓库注册在用户级配置而无需 root 权限。不同 Linux 发行版对 Flathub 的安装指引有所差异，以 Flathub 官方文档为准。

三、安装 Maker

在项目根目录执行：

npm install --save-dev @electron-forge/maker-flatpak

从 package.json 可以看到，@malept/electron-installer-flatpak（^0.11.4）被声明为optionalDependencies：实际的 Flatpak 构建由该底层安装器完成，它只在 Linux 环境下安装；在非 Linux 平台上 npm 会静默跳过。这也解释了为什么 Maker 的isSupportedOnCurrentPlatform()采用this.isInstalled('@malept/electron-installer-flatpak')来判断（见 MakerFlatpak.ts）——能否构建 Flatpak，取决于该底层依赖是否真实可用。

四、在 forge.config.js 中启用 Maker

在 Forge 配置 的makers数组中添加该 Maker（以下为 README 的完整原样示例）：

// forge.config.js module.exports = { makers: [ { name: '@electron-forge/maker-flatpak', config: { options: { categories: ['Video'], mimeType: ['video/h264'] } } } ] };

配置入口结构为config.options：MakerFlatpakConfig接口仅包含options字段（见 Config.ts），所有具体选项定义在MakerFlatpakConfigOptions中，下面逐一详解。

五、配置选项全解析

以下参数全部来自 Config.ts 的类型定义，并注明默认值、用途以及它们最终写入 flatpak-builder manifest 或 desktop 规范的哪个字段。

5.1 基础标识类

5.2 分支与基础应用（BaseApp）

Electron 应用通常通过 BaseApp 机制共享通用运行时骨架，baseFlatpakref可让构建过程自动拉取基础应用。

5.3 运行时与 SDK

这三个默认值对应 Flathub 上最常见的 Freedesktop 运行时/SDK 组合。若应用需要更新的运行时（例如较新的 Electron 依赖更新的 glibc），可显式覆盖runtimeVersion。

5.4 权限与沙箱

示例——为应用授予网络与 X11 显示访问权限：

config: { options: { finishArgs: ['--share=network', '--socket=x11', '--device=all'] } }

这是 Flatpak 沙箱模型的关键配置：未在finish-args中显式授权的资源，应用一律不可访问。

5.5 附加文件与模块

关于files有一个重要边界（Config.ts 注释明确说明）：应用自身的资产与代码由 @electron/packager 全权处理，无需也不应通过files复制；files的真正用途是安装 appstream 元数据、dbus 配置文件等 packager 不会生成的内容。例如：

options: { files: [ ['build/com.example.app.appdata.xml', '/share/appdata/'] ] }

modules则面向"使用原生 Node 模块且依赖特定系统库"的应用，多数 Electron 应用并不需要。

5.6 桌面目录分类与 MIME 类型

categories的合法取值被严格限定为以下 13 个枚举（与 freedesktop 菜单规范一致，见 Config.ts）：

AudioVideo | Audio | Video | Development | Education | Game | Graphics | Network | Office | Science | Settings | System | Utility

README 示例中的['Video']与['video/h264']对应一个"视频播放器/编辑器"类应用：Video决定其在应用菜单中的展示分类，video/h264声明其可处理 H.264 视频的 MIME 类型。

六、底层实现原理：从源码看构建流程

6.1 架构映射表

构建前，Maker 会把 Electron Forge 的架构标识转换为 flatpak-builder 使用的架构名，转换逻辑集中在flatpakArch()（见 MakerFlatpak.ts）：

6.2 make() 调用链

make()的执行流程（MakerFlatpak.ts）：

1. 动态导入底层安装器：await import('@malept/electron-installer-flatpak')，该包没有类型声明，源码用@ts-expect-error标注；
2. 架构转换：通过flatpakArch(targetArch)得到 flatpak 架构名；
3. 计算输出目录：path.resolve(makeDir, 'flatpak', arch)，即产物位于make/flatpak/<arch>/；
4. 清空并重建输出目录：调用基类ensureDirectory()（见 Maker.ts，该操作是破坏性的——目录已存在则删除后重建）；
5. 组装配置：{ ...this.config, arch, src: dir, dest: outDir }，其中src是 @electron/packager 已打包的应用目录，dest是输出目录；
6. 调用安装器：await installer(flatpakConfig)，由它完成 manifest 生成、运行时拉取与 flatpak-builder 调用；
7. 收集产物：扫描输出目录，过滤出所有以.flatpak结尾的文件并返回绝对路径列表，供 Forge 的后续发布流程使用。

6.3 在整个 make 流程中的位置

与所有 Maker 一样，Flatpak Maker 由 make.ts 统一驱动：package（打包应用）→preMake钩子 → 逐架构、逐 Maker 执行make()→postMake钩子 → 保存 make results。多个架构（如 x64 与 arm64）会并行构建，各自的.flatpak产物分别落在make/flatpak/<arch>/下，再由make()的返回值汇总，供electron-forge publish或release使用。

6.4 测试验证

仓库的单元测试 MakerFlatpak.spec.ts 验证了两个关键行为：

• 默认配置透传：mock 底层安装器后，断言其收到的参数为{ arch, src, dest }，且不携带options；
• 配置级联：传入options: { productName: 'Flatpak', files: [] }后，断言这些选项原样传给安装器；同时验证了用户即使传入arch: 'overridden'，最终arch仍为转换后的真实架构。

这从测试角度印证了：arch、src、dest三个字段由 Maker 内部强制接管，写入config会被覆盖；其余选项则原样级联到底层安装器。

七、构建与调试

7.1 触发构建

配置完成后，在项目根目录执行：

npx electron-forge make

Forge 会先执行package，再调用 Flatpak Maker 生成.flatpak产物；也可以只针对该 Maker 构建：

npx electron-forge make --targets @electron-forge/maker-flatpak

7.2 调试日志

官方文档 docs/config/makers/flatpak.md 提供了底层安装器的调试开关：

DEBUG=electron-installer-flatpak* npx electron-forge make

启用后，@malept/electron-installer-flatpak与 flatpak-builder 的调用细节、manifest 生成过程都会输出到控制台，是排查构建失败的第一手段。

八、常见问题速查

• Cannot make for flatpak, the following external binaries need to be installed：缺少flatpak-builder或eu-strip，按发行版安装flatpak-builder与elfutils后重试；
• 构建时拉取运行时失败：确认已执行flatpak remote-add --if-not-exists --user flathub ...，且网络可达 Flathub；
• 提示 maker 不适用当前平台：检查@malept/electron-installer-flatpak是否随 optionalDependencies 安装成功（在 Linux 上一般自动满足）；
• 产物在哪里：out/make/flatpak/<arch>/*.flatpak，其中<arch>为i386/x86_64/arm/aarch64之一。

总结

@electron-forge/maker-flatpak是 Electron Forge 构建沙箱化 Linux 分发物的一站式方案：它把架构映射、manifest 生成、runtime/SDK 拉取、desktop 规范字段填充、finish-args 权限声明等底层细节封装在@malept/electron-installer-flatpak中，开发者只需在 Forge 配置 中声明categories、mimeType、finishArgs、files等选项，即可产出可直接分发的.flatpak安装包。结合源码与测试（MakerFlatpak.ts、Config.ts、MakerFlatpak.spec.ts），本文已完整覆盖从环境准备、安装配置到原理验证的整条链路，可作为你接入 Flatpak 分发时的直接参考。

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