高级安装说明

高级安装说明

¥Advanced Installation Instructions

要安装预构建的 Electron 二进制文件，请使用 npm。首选方法是将 Electron 安装为应用中的开发依赖：

¥To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:

npm install electron --save-dev

有关如何管理应用中的 Electron 版本的信息，请参阅 Electron 版本控制文档。

¥See the Electron versioning doc for info on how to manage Electron versions in your apps.

临时运行 Electron

¥Running Electron ad-hoc

如果你手头紧，不想在本地项目中使用 npm install，你还可以使用与 npm 打包的 npx 命令运行程序来临时运行 Electron：

¥If you're in a pinch and would prefer to not use npm install in your local project, you can also run Electron ad-hoc using the npx command runner bundled with npm:

npx electron .

上面的命令将使用 Electron 运行当前工作目录。请注意，你的应用中的任何依赖都不会安装。

¥The above command will run the current working directory with Electron. Note that any dependencies in your app will not be installed.

定制化

¥Customization

如果你想更改下载的架构（例如，x64 机器上的 ia32），你可以在 npm install 中使用 --arch 标志或设置 npm_config_arch 环境变量：

¥If you want to change the architecture that is downloaded (e.g., ia32 on an x64 machine), you can use the --arch flag with npm install or set the npm_config_arch environment variable:

npm install --arch=ia32 electron

除了更改架构之外，你还可以使用 --platform 标志指定平台（例如 win32、linux 等）：

¥In addition to changing the architecture, you can also specify the platform (e.g., win32, linux, etc.) using the --platform flag:

npm install --platform=win32 electron

代理

¥Proxies

如果你需要使用 HTTP 代理，则需要将 ELECTRON_GET_USE_PROXY 变量设置为任意值，并根据主机系统的 Node 版本添加其他环境变量：

¥If you need to use an HTTP proxy, you need to set the ELECTRON_GET_USE_PROXY variable to any value, plus additional environment variables depending on your host system's Node version:

• 节点 10 及以上

  ¥Node 10 and above

• 节点 10 之前

  ¥Before Node 10

自定义镜像和缓存

¥Custom Mirrors and Caches

在安装过程中，electron 模块将调用 @electron/get 来下载适合你平台的 Electron 预构建二进制文件。它将通过联系 GitHub 的发布下载页面（https://github.com/electron/electron/releases/tag/v$VERSION，其中 $VERSION 是 Electron 的确切版本）来完成此操作。

¥During installation, the electron module will call out to @electron/get to download prebuilt binaries of Electron for your platform. It will do so by contacting GitHub's release download page (https://github.com/electron/electron/releases/tag/v$VERSION, where $VERSION is the exact version of Electron).

如果你无法访问 GitHub 或者需要提供自定义构建，则可以通过提供镜像或现有缓存目录来实现。

¥If you are unable to access GitHub or you need to provide a custom build, you can do so by either providing a mirror or an existing cache directory.

镜像

¥Mirror

你可以使用环境变量来覆盖基本 URL、查找 Electron 二进制文件的路径以及二进制文件名。@electron/get 使用的 URL 组成如下：

¥You can use environment variables to override the base URL, the path at which to look for Electron binaries, and the binary filename. The URL used by @electron/get is composed as follows:

url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME

以使用中国 CDN 镜像为例：

¥For instance, to use the China CDN mirror:

ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

默认情况下，ELECTRON_CUSTOM_DIR 设置为 v$VERSION。要更改格式，请使用 {{ version }} 占位符。例如，version-{{ version }} 解析为 version-5.0.0，{{ version }} 解析为 5.0.0，v{{ version }} 相当于默认值。举个更具体的例子，使用中国非 CDN 镜像：

¥By default, ELECTRON_CUSTOM_DIR is set to v$VERSION. To change the format, use the {{ version }} placeholder. For example, version-{{ version }} resolves to version-5.0.0, {{ version }} resolves to 5.0.0, and v{{ version }} is equivalent to the default. As a more concrete example, to use the China non-CDN mirror:

ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
ELECTRON_CUSTOM_DIR="{{ version }}"

上述配置将从 https://npmmirror.com/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip 等 URL 下载。

¥The above configuration will download from URLs such as https://npmmirror.com/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip.

如果你的镜像提供的工件具有与官方 Electron 版本不同的校验和，你可能必须直接设置 electron_use_remote_checksums=1，或在 .npmrc 文件中配置它，以强制 Electron 使用远程 SHASUMS256.txt 文件而不是嵌入的校验和来验证校验和。

¥If your mirror serves artifacts with different checksums to the official Electron release you may have to set electron_use_remote_checksums=1 directly, or configure it in a .npmrc file, to force Electron to use the remote SHASUMS256.txt file to verify the checksum instead of the embedded checksums.

缓存

¥Cache

或者，你可以覆盖本地缓存。@electron/get 会将下载的二进制文件缓存在本地目录中，以免给你的网络带来压力。你可以使用该缓存文件夹来提供 Electron 的自定义构建或完全避免与网络进行联系。

¥Alternatively, you can override the local cache. @electron/get will cache downloaded binaries in a local directory to not stress your network. You can use that cache folder to provide custom builds of Electron or to avoid making contact with the network at all.

• Linux：$XDG_CACHE_HOME 或 ~/.cache/electron/

  ¥Linux: $XDG_CACHE_HOME or ~/.cache/electron/

• 苹果系统：~/Library/Caches/electron/

  ¥macOS: ~/Library/Caches/electron/

• Windows：$LOCALAPPDATA/electron/Cache 或 ~/AppData/Local/electron/Cache/

  ¥Windows: $LOCALAPPDATA/electron/Cache or ~/AppData/Local/electron/Cache/

在使用旧版本 Electron 的环境中，你可能会发现缓存也在 ~/.electron 中。

¥On environments that have been using older versions of Electron, you might find the cache also in ~/.electron.

你还可以通过提供 electron_config_cache 环境变量来覆盖本地缓存位置。

¥You can also override the local cache location by providing a electron_config_cache environment variable.

缓存包含该版本的官方 zip 文件以及校验和，并存储为 [checksum]/[filename]。典型的缓存可能如下所示：

¥The cache contains the version's official zip file as well as a checksum, and is stored as [checksum]/[filename]. A typical cache might look like this:

├── a91b089b5dc5b1279966511344b805ec84869b6cd60af44f800b363bba25b915
│   └── electron-v15.3.1-darwin-x64.zip

跳过二进制下载

¥Skip binary download

在底层，Electron 的 JavaScript API 绑定到包含其实现的二进制文件。因为这个二进制文件对于任何 Electron 应用的功能都至关重要，所以每次从 npm 注册表安装 electron 时，都会在 postinstall 步骤中默认下载它。

¥Under the hood, Electron's JavaScript API binds to a binary that contains its implementations. Because this binary is crucial to the function of any Electron app, it is downloaded by default in the postinstall step every time you install electron from the npm registry.

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

¥However, 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.

npm

ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install

Yarn

ELECTRON_SKIP_BINARY_DOWNLOAD=1 yarn install

故障排除

¥Troubleshooting

一些用户在运行 npm install electron 时，偶尔会遇到安装错误。

¥When running npm install electron, some users occasionally encounter installation errors.

在几乎所有情况下，这些错误都是网络问题造成的，而不是 electron npm 包的实际问题。诸如 ELIFECYCLE、EAI_AGAIN、ECONNRESET 和 ETIMEDOUT 之类的错误都表明此类网络问题。最好的解决办法是尝试切换网络，或者稍等一下，然后再次尝试安装。

¥In almost all cases, these errors are the result of network problems and not actual issues with the electron npm package. Errors like ELIFECYCLE, EAI_AGAIN, ECONNRESET, and ETIMEDOUT are all indications of such network problems. The best resolution is to try switching networks, or wait a bit and try installing again.

如果通过 npm 安装失败，你还可以尝试直接从 electron/electron/releases 下载 Electron。

¥You can also attempt to download Electron directly from electron/electron/releases if installing via npm is failing.

如果安装失败并出现 EACCESS 错误，你可能需要 修复你的 npm 权限。

¥If installation fails with an EACCESS error you may need to fix your npm permissions.

如果上述错误仍然存在，则可能需要将 unsafe-perm 标志设置为 true：

¥If the above error persists, the unsafe-perm flag may need to be set to true:

sudo npm install electron --unsafe-perm=true

在较慢的网络上，建议使用 --verbose 标志来显示下载进度：

¥On slower networks, it may be advisable to use the --verbose flag in order to show download progress:

npm install --verbose electron

如果你需要强制重新下载资源和 SHASUM 文件，请将 force_no_cache 环境变量设置为 true。

¥If you need to force a re-download of the asset and the SHASUM file set the force_no_cache environment variable to true.