Blogfoon

Blogfoon is a personal space for thoughtful notes on technology, coding, travel, and ordinary life.

  • Published:

What you need first

On a Windows machine, a working Electron setup usually depends on a few specific components:

  • VS 2015
  • 32-bit Node.js
  • 32-bit Python 2.7.x
  • node-gyp

These pieces are what make native module compilation and Electron packaging behave properly in this environment.

Install the required software

Most of the installers can be found in the Electron installation package.

Node.js

Node.js does not require any special steps during installation.

Example download:

https://nodejs.org/dist/v8.11.3/node-v8.11.3-x86.msi

Python

When installing Python 2.7.14, pay attention to the Customize Python 2.7.14 screen. Scroll down and enable Add python to Path, then choose Will be install to... so Python is added to the system environment variables.

If you forget to do that, you can add these paths manually:

  • C:\Python27
  • C:\Python27\Scripts

Yarn

Yarn can replace Npm and usually handles dependency installation faster.

A few basic settings make it much easier to use in China.

1. Cache directory

Check the current cache location:

yarn cache dir

C:\Users\Administrator\AppData\Local\Yarn\Cache\v2

By default the cache is stored on the C drive. You can move it to another drive such as D: to save space and make management easier.

yarn config set cache-folder D:\YarnCache

2. Yarn registry

The default registry may be slow to reach from overseas networks. Switching to a domestic mirror speeds up package downloads.

Check the current registry:

yarn config get registry

https://registry.yarnpkg.com

Switch to the Taobao mirror:

yarn config set registry https://registry.npm.taobao.org

yarn config get registry
https://registry.npm.taobao.org

VS 2015

Extract vs2015.3.com_enu.iso with an unzip tool, then double-click vs_community.exe to begin installation.

You may see a warning during setup; just click Continue.

The default selection is Default. Change it to Custom.

  • Uncheck the default Windows and Web Development option
  • Under Programming Languages, select Visual C++

Then start the installation and wait for it to finish.

Check that everything installed correctly

After installation, confirm the versions from the command line:

输入： python -V
输出： Python 2.7.14

输入： node -v
输出： v8.11.3

输入： yarn -v
输出： 1.10.1

Configure the Electron mirror

Electron installation requires downloading prebuilt runtime packages. Because those packages are hosted on overseas servers, downloads can be very slow or fail entirely. To make Electron usable, you need to set up a separate mirror.

Go to Computer → Properties → Advanced system settings → Environment Variables → New user variable.

Set the variable name to:

ELECTRON_MIRROR

Set the value to:

http://npm.taobao.org/mirrors/electron/

Then reopen your cmd or PowerShell window.

To test it, install Electron globally:

yarn global add [email protected]

After the global installation, you should be able to find the downloaded Electron package under C:\Users\Administrator\.electron. If you install Electron without the global keyword, the cache location is different: C:\Users\Administrator\AppData\Local\electron\Cache.

No matter whether global is used or not, Electron checks its cache in this order:

  1. C:\Users\Administrator\.electron
  2. C:\Users\Administrator\AppData\Local\electron\Cache

This mirror setting is also used by electron-builder when packaging the app.

Download Node.js headers

Some dependency modules, such as ffi and sqlite, need to be compiled before use. These modules rely on system-level dynamic libraries, and compiling from source helps keep them cross-platform. That compilation process requires Node.js header files.

# 全局安装 node-gyp
yarn global add node-gyp

# 下载头文件
# Cmd下运行，Powershell运行可能报错
node-gyp install --dist-url https://npm.taobao.org/mirrors/node

Running this command downloads the header files for the Node.js version currently installed on the system. The headers are saved in C:\Users\Administrator\.node-gyp.

On Windows, if you want a command like yarn add ffi to install successfully and run under Node.js, you need the VS compiler, Python, and the Node.js headers. None of them can be missing. When npm or Yarn installs a package that depends on native compilation, it automatically uses the bundled node-gyp to build it.

Download Electron headers

Electron supports Node native modules, but it uses a different V8 engine from official Node.js. That means a module such as ffi, even if it has already been built against Node.js headers in the previous step, still cannot be used directly inside Electron. It must be rebuilt again with Electron headers.

That means node-gyp needs to be pointed at Electron's header files manually.

Official Electron headers:

https://atom.io/download/electron

Domestic mirror for Electron headers:

https://npm.taobao.org/mirrors/atom-shell/

When downloading the headers, be sure to use the domestic mirror, or the request may time out.

node-gyp install --target=2.0.0 --arch=ia32 --dist-url=https://npm.taobao.org/mirrors/atom-shell/

Here:

  • target is the Electron version and should match the version used in package.json under build → electronVersion
  • arch is the platform architecture, either ia32 or x64

The downloaded headers are also stored in C:\Users\Administrator\.node-gyp.

One detail worth noting: depending on the Electron version, the folder name may vary, such as iojs-1.8.2, iojs-2.0.0, or 4.0.0.

Manual rebuild for modules, if needed

Suppose ffi was installed in the previous step. You can run the following command in the same directory to rebuild it with Electron headers, so it can be used inside Electron:

cd ./node_modules/ffi/ && node-gyp rebuild --target=2.0.0 --arch=ia32 --target_arch=ia32 && cd ../ref && node-gyp rebuild --target=2.0.0 --arch=ia32 --target_arch=ia32

Two practical notes:

  1. You can save this command in the scripts section of package.json under something like rebuild-ffi, then run it later with yarn run rebuild-ffi.
  2. This step is optional, because the packaging tool introduced below provides commands that can rebuild modules automatically, which is simpler.

Install the packaging tool

electron-builder is a convenient and flexible way to create installers for Electron apps. The build field in package.json contains its configuration, and adding "postinstall": "install-app-deps" under scripts tells the project to rebuild dependencies after each npm or Yarn install. install-app-deps is provided by Electron Builder.

The version used by SmartLinkey 2.1 is:

λ electron-builder.cmd --version
20.28.4

Install globally

yarn global add [email protected]

Configure the headers for install-app-deps

The install-app-deps command provided by Electron Builder removes the need to type node-gyp rebuild... by hand. node-gyp uses the headers stored in C:\Users\Administrator\.node-gyp, while install-app-deps expects headers under C:\Users\Administrator\.electron-gyp.

So you need to do this manually: copy C:\Users\Administrator\.node-gyp\iojs-2.0.0 into C:\Users\Administrator\.electron-gyp.

This prevents install-app-deps from trying to download headers from overseas again and failing. This step depends on what was covered in the Electron header section above.

After that, running yarn inside the SmartLinkey 2.1 project directory to install dependencies and trigger automatic rebuilding should no longer produce errors.

Add the winCodeSign dependency

Try packaging the app from the project root:

# 此时运行会报错
electron-builder .

At this point, the process may hang because electron-builder needs to download some build dependencies from overseas.

You may see output like this:

  • downloading               parts=1 size=4.9 MB url=https://github.com/electron-userland/electron-builder-binaries/releases/download/winCodeSign-2.3.1/winCodeSign-2.3.1.7z

...

4murl=https://github.com/electron-userland/electron-builder-binaries/release
s/download/nsis-3.0.3.2/nsis-3.0.3.2.7z

If it stays stuck for a long time, there are two ways to deal with it:

  1. Copy the required version of the dependency manually into the right folder
  2. Download the exact version shown in the console output and place it in the matching folder

If you installed [email protected], the package already includes the bundled dependency archive, electron-builder-20.28.4.7z. You can unzip it and place its contents in the Cache directory using this structure:

C:\Users\Administrator\AppData\Local\electron-builder\Cache\winCodeSign\winCodeSign-2.3.1

The second option is to read the version number from the error output. For example, if the download fails for winCodeSign-2.3.1, go to GitHub, find that exact package, download it, and extract it into the appropriate electron-builder Cache folder. If NSIS also fails afterward, download nsis-3.0.3.2.7z the same way and place it there as well.

GitHub release page:

https://github.com/electron-userland/electron-builder-binaries/releases

Unzip both archives and put them into the Cache folder. Use the structure inside electron-builder-20.28.4.7z as your reference.

Build the installer

Run electron-builder . again to generate the installation package. If everything is set up correctly, the installer will appear in the elect_builder_output directory.

At this point, the Electron development environment is ready.

Related Posts