Skip to main content

环境变量

🌐 Environment Variables

控制应用的配置和行为，而无需更改代码。

某些 Electron 行为由环境变量控制，因为它们比命令行参数和应用的代码更早初始化。

🌐 Certain Electron behaviors are controlled by environment variables because they are initialized earlier than the command line flags and the app's code.

POSIX shell 示例：

🌐 POSIX shell example:

$ export ELECTRON_ENABLE_LOGGING=true
$ electron

Windows 控制台示例：

🌐 Windows console example:

> set ELECTRON_ENABLE_LOGGING=true
> electron

生产变量​

🌐 Production Variables

以下环境变量主要用于打包后的 Electron 应用运行时。

🌐 The following environment variables are intended primarily for use at runtime in packaged Electron applications.

NODE_OPTIONS​

Electron 包含对 Node 的 NODE_OPTIONS 子集的支持。大多数功能都得到支持，除了与 Chromium 使用 BoringSSL 冲突的那些。

🌐 Electron includes support for a subset of Node's NODE_OPTIONS. The majority are supported with the exception of those which conflict with Chromium's use of BoringSSL.

示例：

🌐 Example:

export NODE_OPTIONS="--no-warnings --max-old-space-size=2048"

不支持的选项有：

🌐 Unsupported options are:

--use-bundled-ca
--force-fips
--enable-fips
--openssl-config
--use-openssl-ca

在打包应用中明确禁止使用 NODE_OPTIONS，但以下情况除外：

--max-http-header-size
--http-parser

如果nodeOptions保险丝被禁用，NODE_OPTIONS将被忽略。

🌐 If the nodeOptions fuse is disabled, NODE_OPTIONS will be ignored.

NODE_EXTRA_CA_CERTS​

详情请参阅 Node.js 命令行文档。

🌐 See Node.js cli documentation for details.

export NODE_EXTRA_CA_CERTS=/path/to/cert.pem

如果nodeOptions保险丝被禁用，NODE_EXTRA_CA_CERTS将被忽略。

🌐 If the nodeOptions fuse is disabled, NODE_EXTRA_CA_CERTS will be ignored.

GOOGLE_API_KEY​

在 Electron 中使用地理位置功能需要使用 Google 云平台的地理位置网络服务。要启用此功能，请获取一个 Google API 密钥，并在打开任何会发起地理位置请求的浏览器窗口之前，将以下代码放入你的主进程文件中：

🌐 Geolocation support in Electron requires the use of Google Cloud Platform's geolocation webservice. To enable this feature, acquire a Google API key and place the following code in your main process file, before opening any browser windows that will make geolocation requests:

process.env.GOOGLE_API_KEY = 'YOUR_KEY_HERE'

默认情况下，新生成的 Google API 密钥可能无法进行地理位置请求。要为你的项目启用地理位置 Web 服务，请通过API 库启用它。

🌐 By default, a newly generated Google API key may not be allowed to make geolocation requests. To enable the geolocation webservice for your project, enable it through the API library.

注意：你需要为与 API 密钥相关的项目添加一个结算账户，以使地理定位 Web 服务正常工作。

🌐 N.B. You will need to add a Billing Account to the project associated to the API key for the geolocation webservice to work.

ELECTRON_NO_ASAR​

禁用 ASAR 支持。此变量仅在分叉的子进程和设置了 ELECTRON_RUN_AS_NODE 的生成子进程中受支持。

🌐 Disables ASAR support. This variable is only supported in forked child processes and spawned child processes that set ELECTRON_RUN_AS_NODE.

ELECTRON_RUN_AS_NODE​

作为普通 Node.js 进程启动该进程。

🌐 Starts the process as a normal Node.js process.

在此模式下，你可以像运行普通 Node.js 可执行文件一样，将 CLI 选项 传递给 Node.js，但以下标志除外：

🌐 In this mode, you will be able to pass cli options to Node.js as you would when running the normal Node.js executable, with the exception of the following flags:

  • "--openssl-config"
  • "--use-bundled-ca"
  • "--use-openssl-ca",
  • "--force-fips"
  • "--enable-fips"

由于 Electron 在构建 Node.js 的 crypto 模块时使用 BoringSSL 而不是 OpenSSL，因此这些标志被禁用，无法按预期工作。

🌐 These flags are disabled owing to the fact that Electron uses BoringSSL instead of OpenSSL when building Node.js' crypto module, and so will not work as designed.

如果runAsNode保险丝被禁用，ELECTRON_RUN_AS_NODE将被忽略。

🌐 If the runAsNode fuse is disabled, ELECTRON_RUN_AS_NODE will be ignored.

ELECTRON_NO_ATTACH_CONSOLE Windows​

不要附加到当前控制台会话。

🌐 Don't attach to the current console session.

ELECTRON_FORCE_WINDOW_MENU_BAR Linux​

不要在 Linux 上使用全局菜单栏。

🌐 Don't use the global menu bar on Linux.

ELECTRON_TRASH Linux​

在 Linux 上设置垃圾箱实现。默认是 gio。

🌐 Set the trash implementation on Linux. Default is gio.

选项：

🌐 Options:

  • gvfs-trash
  • trash-cli
  • kioclient5
  • kioclient

开发变量​

🌐 Development Variables

以下环境变量主要用于开发和调试目的。

🌐 The following environment variables are intended primarily for development and debugging purposes.

ELECTRON_ENABLE_LOGGING​

将 Chromium 的内部日志记录打印到控制台。

🌐 Prints Chromium's internal logging to the console.

设置此变量与在命令行上传递 --enable-logging 是一样的。更多信息，请参见 命令行开关 中的 --enable-logging。

🌐 Setting this variable is the same as passing --enable-logging on the command line. For more info, see --enable-logging in command-line switches.

ELECTRON_LOG_FILE​

设置 Chromium 内部日志记录的文件目标。

🌐 Sets the file destination for Chromium's internal logging.

设置此变量与在命令行上传递 --log-file 是一样的。更多信息，请参见 命令行开关 中的 --log-file。

🌐 Setting this variable is the same as passing --log-file on the command line. For more info, see --log-file in command-line switches.

ELECTRON_DEBUG_NOTIFICATIONS​

在 macOS 上为 Notification 生命周期添加额外日志以辅助调试。当创建或激活新通知时，将显示额外日志。当执行常见操作时也会显示这些日志：通知被显示、被关闭、按钮被点击或回复时。

🌐 Adds extra logs to Notification lifecycles on macOS to aid in debugging. Extra logging will be displayed when new Notifications are created or activated. They will also be displayed when common actions are taken: a notification is shown, dismissed, its button is clicked, or it is replied to.

示例输出：

🌐 Sample output:

Notification created (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)
Notification displayed (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)
Notification activated (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)
Notification replied to (com.github.Electron:notification:EAF7B87C-A113-43D7-8E76-F88EC9D73D44)

ELECTRON_DEBUG_MSIX_UPDATER​

在 Windows 上为 MSIX 更新程序操作添加额外日志，以帮助调试。当启动 MSIX 更新操作时，包括程序包更新、程序包注册和重启注册，将显示额外的日志。这有助于诊断 MSIX 程序包更新和部署的问题。

🌐 Adds extra logs to MSIX updater operations on Windows to aid in debugging. Extra logging will be displayed when MSIX update operations are initiated, including package updates, package registration, and restart registration. This helps diagnose issues with MSIX package updates and deployments.

示例输出：

🌐 Sample output:

UpdateMsix called with URI: https://example.com/app.msix
DoUpdateMsix: Starting
Calling AddPackageByUriAsync... URI: https://example.com/app.msix
Update options - deferRegistration: true, developerMode: false, forceShutdown: false, forceTargetShutdown: false, forceUpdateFromAnyVersion: false
Waiting for deployment...
Deployment finished.
MSIX Deployment completed.

ELECTRON_LOG_ASAR_READS​

当 Electron 从 ASAR 文件中读取时，将读取偏移量和文件路径记录到系统 tmpdir。生成的文件可以提供给 ASAR 模块，以优化文件排序。

🌐 When Electron reads from an ASAR file, log the read offset and file path to the system tmpdir. The resulting file can be provided to the ASAR module to optimize file ordering.

ELECTRON_ENABLE_STACK_DUMPING​

当 Electron 崩溃时，将堆栈跟踪打印到控制台。

🌐 Prints the stack trace to the console when Electron crashes.

如果启动 crashReporter，此环境变量将不起作用。

🌐 This environment variable will not work if the crashReporter is started.

ELECTRON_DEFAULT_ERROR_MODE Windows​

当 Electron 崩溃时显示 Windows 的崩溃对话框。

🌐 Shows the Windows's crash dialog when Electron crashes.

如果启动 crashReporter，此环境变量将不起作用。

🌐 This environment variable will not work if the crashReporter is started.

ELECTRON_OVERRIDE_DIST_PATH​

在运行 electron 包时，该变量会告诉 electron 命令使用指定的 Electron 构建，而不是 npm install 下载的版本。用法：

🌐 When running from the electron package, this variable tells the electron command to use the specified build of Electron instead of the one downloaded by npm install. Usage:

export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing

ELECTRON_SKIP_BINARY_DOWNLOAD​

如果你想安装项目的依赖，但不需要使用 Electron 功能，你可以设置 ELECTRON_SKIP_BINARY_DOWNLOAD 环境变量以防止下载二进制文件。例如，当在持续集成环境中运行对 electron 模块进行模拟的单元测试时，这个功能可能会很有用。

🌐 If you want to install your project's dependencies but don't need to use Electron functionality, you can set the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable to prevent the binary from being downloaded. For instance, this feature can be useful in continuous integration environments when running unit tests that mock out the electron module.

ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install