高级安装说明
¥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:
自定义镜像和缓存
¥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
- Yarn
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install
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
.