配置 Electron Fuses

注意

以下信息部分复制自与 @electron/fuses 和 electron 教程的集成，以便于阅读/访问。

什么是 fuses？¶

对于 Electron 功能的子集，禁用整个应用程序的某些功能是有意义的。例如，99% 的应用程序不使用 ELECTRON_RUN_AS_NODE，这些应用程序希望能够发布一个无法使用该功能的二进制文件。我们也不希望 Electron 用户从源代码构建 Electron，因为这既是一个巨大的技术挑战，又需要花费大量的时间和金钱。

Fuses 是解决此问题的方法，从高层次来看，它们是 Electron 二进制文件中的“魔法位”，可以在打包 Electron 应用程序时翻转这些位，以启用/禁用某些功能/限制。由于它们在代码签名应用程序之前在打包时被翻转，因此操作系统负责确保这些位不会通过操作系统级别的代码签名验证（Gatekeeper / App Locker）被翻转回来。

如何翻转 fuses？¶

在底层，electron-builder 利用官方的 @electron/fuses 模块来简化 fuses 的翻转。以前，electron fuses 只能在 afterPack 钩子中翻转（这仍然是一种支持的方法）。现在，您可以改为设置 electron-builder 配置属性 electronFuses: FuseOptionsV1 来激活 electron-builder 的集成。

示例¶

注意

下面的 true/false 只是一个示例，请根据您自己的需求自定义您的配置

electronFuses: {
  runAsNode: false,
  enableCookieEncryption: true,
  enableNodeOptionsEnvironmentVariable: false,
  enableNodeCliInspectArguments: false,
  enableEmbeddedAsarIntegrityValidation: true,
  onlyLoadAppFromAsar: true,
  loadBrowserProcessSpecificV8Snapshot: false,
  grantFileProtocolExtraPrivileges: false
}

仍然可以在 afterPack 钩子中继续保留您当前的逻辑流程，因此在 PlatformPackager 中公开了一种便捷方法，可以轻松自定义您自己的标志。它直接接受 AfterPackContext 和 type 的 FuseConfig 对象。打开此便捷方法是为了可以提供自定义的 FuseConfig，允许使用 strictlyRequireAllFuses 来监视您的 fuses 并与发布的 fuses 保持同步，和/或强制覆盖 electron-builder 中的 @electron/fuses 版本（如果您想利用更新）。

afterPack.ts

const { FuseConfig, FuseVersion, FuseV1Options } = require("@electron/fuses")

exports.default = function (context: AfterPackContext) {
  const fuses: FuseConfig = {
    version: FuseVersion.V1,
    strictlyRequireAllFuses: true,
    [FuseV1Options.RunAsNode]: false,
    ... // all other flags must be specified since `strictlyRequireAllFuses = true`
  }
  await context.packager.addElectronFuses(context, fuses)
}

验证 Fuses¶

您可以使用 fuses CLI 验证 fuses 是否已翻转或检查任意 Electron 应用程序的 fuse 状态。

npx @electron/fuses read --app /Applications/Foo.app

Typedoc¶

Electron-Builder / app-builder-lib / FuseOptionsV1

所有选项均来自 @electron/fuses 参考：https://raw.githubusercontent.com/electron/electron/refs/heads/main/docs/tutorial/fuses.md

属性¶

enableCookieEncryption?¶

optional enableCookieEncryption: boolean

cookieEncryption fuse 切换是否使用操作系统级别的加密密钥加密磁盘上的 cookie 存储。默认情况下，Chromium 用于存储 cookie 的 sqlite 数据库以明文形式存储值。如果您希望确保您的应用程序 cookie 以与 Chrome 相同的方式加密，则应启用此 fuse。请注意，这是一个单向转换，如果您启用此 fuse，现有的未加密 cookie 将在写入时加密，但如果您随后再次禁用该 fuse，您的 cookie 存储将有效地损坏且无法使用。大多数应用程序可以安全地启用此 fuse。

enableEmbeddedAsarIntegrityValidation?¶

optional enableEmbeddedAsarIntegrityValidation: boolean

embeddedAsarIntegrityValidation fuse 切换 macOS 上的一个实验性功能，该功能在加载 app.asar 文件时验证其内容。此功能旨在最大限度地减少性能影响，但可能会略微减慢从 app.asar 存档内部读取文件的速度。目前，electron>=16.0.0 的 macOS 支持 ASAR 完整性检查

macOS as of electron>=16.0.0
Windows as of electron>=30.0.0

有关如何使用 asar 完整性验证的更多信息，请阅读 Asar 完整性文档。

enableNodeCliInspectArguments?¶

optional enableNodeCliInspectArguments: boolean

nodeCliInspect fuse 切换是否遵守 --inspect、--inspect-brk 等标志。禁用后，它还可以确保 SIGUSR1 信号不会初始化主进程检查器。大多数应用程序可以安全地禁用此 fuse。

enableNodeOptionsEnvironmentVariable?¶

optional enableNodeOptionsEnvironmentVariable: boolean

nodeOptions fuse 切换是否遵守 NODE_OPTIONS 和 NODE_EXTRA_CA_CERTS 环境变量。NODE_OPTIONS 环境变量可用于将各种自定义选项传递给 Node.js 运行时，并且通常不被生产环境中的应用程序使用。大多数应用程序可以安全地禁用此 fuse。

grantFileProtocolExtraPrivileges?¶

optional grantFileProtocolExtraPrivileges: boolean

grantFileProtocolExtraPrivileges fuse 更改是否为从 file:// 协议加载的页面授予超出传统 Web 浏览器中接收的权限。此行为是 Electron 早期版本中 Electron 应用程序的核心，但现在不再需要，因为应用程序现在应该从自定义协议提供本地文件。如果您不是从 file:// 提供页面，则应禁用此 fuse。此 fuse 授予 file:// 协议的额外权限在下面未完全记录

file:// 协议页面可以使用 fetch 加载其他 file:// 上的资源
file:// 协议页面可以使用 service workers
file:// 协议页面对也在 file:// 协议上运行的子框架具有通用访问权限，无论 sandbox 设置如何

loadBrowserProcessSpecificV8Snapshot?¶

optional loadBrowserProcessSpecificV8Snapshot: boolean

loadBrowserProcessSpecificV8Snapshot fuse 更改哪个 V8 快照文件用于浏览器进程。默认情况下，Electron 的进程都将使用相同的 V8 快照文件。启用此 fuse 后，浏览器进程将使用名为 browser_v8_context_snapshot.bin 的文件作为其 V8 快照。其他进程将使用他们通常使用的 V8 快照文件。

onlyLoadAppFromAsar?¶

optional onlyLoadAppFromAsar: boolean

onlyLoadAppFromAsar fuse 更改 Electron 用于定位您的应用程序代码的搜索系统。默认情况下，Electron 将按以下顺序搜索 app.asar -> app -> default_app.asar。启用此 fuse 后，搜索顺序将变为单个条目 app.asar，从而确保与 embeddedAsarIntegrityValidation fuse 结合使用时，不可能加载未验证的代码。

resetAdHocDarwinSignature?¶

optional resetAdHocDarwinSignature: boolean

重置应用程序签名，专门用于 macOS。注意：由于 electron-builder 在翻转 fuses 后直接签名应用程序，因此这应该是没有必要的。参考：https://github.com/electron/fuses?tab=readme-ov-file#apple-silicon

runAsNode?¶

optional runAsNode: boolean

runAsNode fuse 切换是否遵守 ELECTRON_RUN_AS_NODE 环境变量。请注意，如果禁用此 fuse，则主进程中的 process.fork 将无法按预期工作，因为它依赖于此环境变量才能运行。相反，我们建议您使用 Utility Processes，它适用于许多需要独立 Node.js 进程的用例（例如 Sqlite 服务器进程或类似场景）。