Electron Cross-Compile: Linux → Windows

Build Windows exe/msi/installer from an Electron project on a Linux host.

Prerequisites

Node.js 18+ and npm
Disk space: at least 300MB free per build (electron binary ~115MB + app + NSIS output ~160MB)
wine for NSIS installer signing step (even without a certificate, makensis needs wine)

Step-by-Step

1. Install Wine (required for NSIS on Linux)

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install -y wine32:i386 wine64

Verify: wine --version — wine32 warnings about display driver are harmless for CLI usage.

2. Disable Code Signing (no certificate scenario)

Edit package.json build config:

"win": {
  "target": ["nsis", "portable"],
  "icon": "assets/icon.ico",
  "signAndEditExecutable": false,
  "sign": null
}

Key pitfalls:

"sign": false does NOT work — must be null
"signingHashAlgorithms": [] causes schema validation error — use sign: null instead
Without wine installed, electron-builder fails with ERR_ELECTRON_BUILDER_CANNOT_EXECUTE even with signing disabled

3. Generate Icon Files (if missing)

from PIL import Image, ImageDraw
img = Image.new('RGB', (256, 256), '#1a1a2e')
draw = ImageDraw.Draw(img)
draw.rectangle([40, 40, 216, 216], fill='#16213e', outline='#0f3460', width=3)
img.save('assets/icon.png')
img.save('assets/icon.ico', format='ICO', sizes=[(16,16),(32,32),(48,48),(64,64),(128,128),(256,256)])

Both .ico (Windows) and .png (Linux) needed depending on targets.

4. Install Dependencies & Build

cd /path/to/electron-project
npm install
# If using electron-vite, build the renderer/main/preload first:
npx electron-vite build   # produces out/ directory
# Then package:
npx electron-builder --win --x64

If rcedit fails with USER32.dll not found, the root cause is that wine32 prefix was initialized without an X display server. wine cannot create its internal DLL stubs (user32.dll etc.) without X11, even for headless CLI usage. Fix: start Xvfb before initializing the wine prefix:

# Step 1: Install Xvfb (usually pre-installed on Ubuntu server)
sudo apt-get install -y xvfb

# Step 2: Start Xvfb in background
Xvfb :99 -screen 0 1024x768x24 &

# Step 3: (Re)create the wine32 prefix WITH display available
rm -rf ~/.wine32
DISPLAY=:99 WINEARCH=win32 WINEPREFIX=~/.wine32 wineboot --init

# Step 4: Verify user32.dll was generated
find ~/.wine32 -name "user32.dll"  # should find it

# Step 5: Run electron-builder with the wine32 prefix and display
DISPLAY=:99 WINEARCH=win32 WINEPREFIX=~/.wine32 npx electron-builder --win --x64

Key insight: sudo apt install wine32:i386 alone is NOT sufficient — the wine prefix must be initialized with DISPLAY set, or user32.dll and other system DLL stubs won't be generated.

5. Output Files

File	Description
`dist/AppName Setup X.X.X.exe`	NSIS installer (per-user by default)
`dist/AppName X.X.X.exe`	Portable standalone (no install needed)
`dist/win-unpacked/`	Unpacked directory (can be deleted to save space)

6. Upload for Download

# COS upload example
source ~/.hermes/custom_services.env
coscmd config -a "$COS_SECRET_ID" -s "$COS_SECRET_KEY" -b "$COS_BUCKET_NAME" -r "$COS_REGION"
coscmd upload "dist/AppName X.X.X.exe" tools/AppName-X.X.X-Portable.exe

COS URL pattern: https://{bucket}.cos.{region}.myqcloud.com/tools/{filename}

Pitfalls

Disk space exhaustion: NSIS needs ~160MB temp space. If disk is >95% full, makensis crashes with can't write N bytes to output — BUT the portable exe may already be written successfully before the error. Check dist/ for valid PE32 files.
Wine display driver errors: nodrv_CreateWindow errors are harmless — wine works for CLI signing steps without X11.
sign: false vs sign: null: false is ignored by electron-builder; must use null to fully skip signing.
extraResources paths: Relative paths like ../extension are resolved from the package.json directory. Missing source dirs cause silent failures.
No code signing = SmartScreen warning: Windows users will see "Unknown publisher" — instruct them to click "More info" → "Run anyway".
wine rcedit-ia32.exe USER32.dll not found: When running electron-builder --win on Linux, it uses wine to run rcedit-ia32.exe (from ~/.cache/electron-builder/winCodeSign/) to set exe metadata/icon. Error: Library USER32.dll not found. Root cause: wine32 prefix was initialized without an X display server, so wine couldn't generate system DLL stubs. Fix: Start Xvfb (Xvfb :99 -screen 0 1024x768x24 &), then re-create the wine32 prefix with DISPLAY=:99 WINEARCH=win32 WINEPREFIX=~/.wine32 wineboot --init, then run electron-builder with DISPLAY=:99 WINEPREFIX=~/.wine32. Simply installing wine32:i386 is NOT enough — the prefix needs X11 to properly initialize. As a last resort, zip dist/win-unpacked/ and run the exe directly.
electron-vite projects: If the project uses electron-vite, run npx electron-vite build first (produces out/ directory), then npx electron-builder --win --x64. Do NOT skip the vite build step.
🔥 npmRebuild: false packages Linux native .node into Windows build: If electron-builder.yml has npmRebuild: false (common for speed), any native Node addon (e.g. better-sqlite3) compiled on Linux will be packaged as a Linux ELF .node binary. On Windows, loading this crashes the app silently. Verify after build: file dist/win-unpacked/resources/app.asar.unpacked/**/better_sqlite3.node — should say PE32+ executable not ELF. Fix: Either set npmRebuild: true (slow, needs Windows toolchain on Linux via wine), or exclude the native module and use a pure-JS alternative (like sql.js for SQLite). For projects that only use native modules in optional code paths, you can also exclude them from files in electron-builder.yml and handle the import failure gracefully at runtime.

User Instructions Template

When delivering unsigned exe to user:

Warn about "Unknown publisher" SmartScreen warning
Recommend Portable exe for quick test, Setup exe for permanent install
Remind about Chrome Extension manual loading if applicable

6.5 KiB Raw Blame History