跳转到主内容

Electron Fuses

包特性切换

什么是 fuses ？​

对于某些基于 Electron 的功能性应用，为整个应用程序禁用某些功能是具有意义的。 例如，99%的应用都没有使用ELECTRON_RUN_AS_NODE。它们希望能够提供无法使用该功能的二进制文件。 我们也不想要让 Electron 的使用者使用源代码重新编译构建 Electron ，因为这不但具有巨大的技术挑战，而且会花费高昂的时间、金钱成本。

Fuses 是这些问题的一个解决方案。它们在 Electron 二进制文件中有“魔法”，可以使您在打包您的 Electron 时选择启用或者禁用某些功能（限制） Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).

Current Fuses​

runAsNode​

Default: Enabled

@electron/fuses: FuseV1Options.RunAsNode

The runAsNode fuse toggles whether the ELECTRON_RUN_AS_NODE environment variable is respected or not. Please note that if this fuse is disabled then process.fork in the main process will not function as expected as it depends on this environment variable to function. Instead, we recommend that you use Utility Processes, which work for many use cases where you need a standalone Node.js process (like a Sqlite server process or similar scenarios).

cookieEncryption​

Default: Disabled

@electron/fuses: FuseV1Options.EnableCookieEncryption

The cookieEncryption fuse toggles whether the cookie store on disk is encrypted using OS level cryptography keys. By default the sqlite database that Chromium uses to store cookies stores the values in plaintext. If you wish to ensure your apps cookies are encrypted in the same way Chrome does then you should enable this fuse. Please note it is a one-way transition, if you enable this fuse existing unencrypted cookies will be encrypted-on-write but if you then disable the fuse again your cookie store will effectively be corrupt and useless. Most apps can safely enable this fuse.

nodeOptions​

Default: Enabled

@electron/fuses: FuseV1Options.EnableNodeOptionsEnvironmentVariable

The nodeOptions fuse toggles whether the NODE_OPTIONS and NODE_EXTRA_CA_CERTS environment variables are respected. The NODE_OPTIONS environment variable can be used to pass all kinds of custom options to the Node.js runtime and isn't typically used by apps in production. Most apps can safely disable this fuse.

nodeCliInspect​

Default: Enabled

@electron/fuses: FuseV1Options.EnableNodeCliInspectArguments

The nodeCliInspect fuse toggles whether the --inspect, --inspect-brk, etc. flags are respected or not. When disabled it also ensures that SIGUSR1 signal does not initialize the main process inspector. Most apps can safely disable this fuse.

embeddedAsarIntegrityValidation​

Default: Disabled

@electron/fuses: FuseV1Options.EnableEmbeddedAsarIntegrityValidation

The embeddedAsarIntegrityValidation fuse toggles an experimental feature on macOS that validates the content of the app.asar file when it is loaded. This feature is designed to have a minimal performance impact but may marginally slow down file reads from inside the app.asar archive.

For more information on how to use asar integrity validation please read the Asar Integrity documentation.

onlyLoadAppFromAsar​

Default: Disabled

@electron/fuses: FuseV1Options.OnlyLoadAppFromAsar

The onlyLoadAppFromAsar fuse changes the search system that Electron uses to locate your app code. By default Electron will search in the following order app.asar -> app -> default_app.asar. When this fuse is enabled the search order becomes a single entry app.asar thus ensuring that when combined with the embeddedAsarIntegrityValidation fuse it is impossible to load non-validated code.

loadBrowserProcessSpecificV8Snapshot​

Default: Disabled

@electron/fuses: FuseV1Options.LoadBrowserProcessSpecificV8Snapshot

The loadBrowserProcessSpecificV8Snapshot fuse changes which V8 snapshot file is used for the browser process. By default Electron's processes will all use the same V8 snapshot file. When this fuse is enabled the browser process uses the file called browser_v8_context_snapshot.bin for its V8 snapshot. The other processes will use the V8 snapshot file that they normally do.

V8 snapshots can be useful to improve app startup performance. V8 lets you take snapshots of initialized heaps and then load them back in to avoid the cost of initializing the heap.

Using separate snapshots for renderer processes and the main process can improve security, especially to make sure that the renderer doesn't use a snapshot with nodeIntegration enabled. See #35170 for details.

grantFileProtocolExtraPrivileges​

Default: Enabled

@electron/fuses: FuseV1Options.GrantFileProtocolExtraPrivileges

The grantFileProtocolExtraPrivileges fuse changes whether pages loaded from the file:// protocol are given privileges beyond what they would receive in a traditional web browser. This behavior was core to Electron apps in original versions of Electron but is no longer required as apps should be serving local files from custom protocols now instead. If you aren't serving pages from file:// you should disable this fuse.

The extra privileges granted to the file:// protocol by this fuse are incompletely documented below:

  • file:// protocol pages can use fetch to load other assets over file://
  • file:// protocol pages can use service workers
  • file:// protocol pages have universal access granted to child frames also running on file:// protocols regardless of sandbox settings

How do I flip the fuses?​

简易方式​

We've made a handy module, @electron/fuses, to make flipping these fuses easy. Check out the README of that module for more details on usage and potential error cases.

const { flipFuses, FuseVersion, FuseV1Options } = require('@electron/fuses')

flipFuses(
  // Path to electron
  require('electron'),
  // Fuses to flip
  {
    version: FuseVersion.V1,
    [FuseV1Options.RunAsNode]: false
  }
)

You can validate the fuses have been flipped or check the fuse status of an arbitrary Electron app using the fuses CLI.

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

复杂方式​

快速术语表​

  • Fuse Wire: A sequence of bytes in the Electron binary used to control the fuses
  • Sentinel: A static known sequence of bytes you can use to locate the fuse wire
  • Fuse Schema: The format / allowed values for the fuse wire

Manually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.

Somewhere in the Electron binary there will be a sequence of bytes that look like this:

| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |
  • sentinel_bytes is always this exact string dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX
  • fuse_version is a single byte whose unsigned integer value represents the version of the fuse schema
  • fuse_wire_length is a single byte whose unsigned integer value represents the number of fuses in the following fuse wire
  • fuse_wire is a sequence of N bytes, each byte represents a single fuse and its state.
    • "0" (0x30) indicates the fuse is disabled
    • "1" (0x31) indicates the fuse is enabled
    • "r" (0x72) indicates the fuse has been removed and changing the byte to either 1 or 0 will have no effect.

To flip a fuse you find its position in the fuse wire and change it to "0" or "1" depending on the state you'd like.

您可以在 这里查看当前schema。