Add devops/electron-build
This commit is contained in:
@@ -0,0 +1,136 @@
|
||||
---
|
||||
name: electron-build
|
||||
description: "Electron desktop app builds: cross-compile for Windows on Linux and fix bundled Chromium DLL issues."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [electron, windows, cross-compile, nsis, exe, msi, wine, chromium, dll-fix, build]
|
||||
related_skills: [hermes-desktop-build]
|
||||
---
|
||||
|
||||
# Electron Build
|
||||
|
||||
Two build/deploy concerns for Electron desktop apps: cross-compiling for Windows from Linux, and fixing bundled Chromium DLL issues on Windows.
|
||||
|
||||
## Section 1: Cross-Compile Linux → Windows
|
||||
|
||||
Build Windows exe/msi/installer from an Electron project on a Linux host.
|
||||
|
||||
**When to use:** Building Electron apps for Windows users from a Linux CI/CD server.
|
||||
|
||||
### 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)
|
||||
|
||||
### Install Wine
|
||||
|
||||
```bash
|
||||
sudo dpkg --add-architecture i386
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y wine32:i386 wine64
|
||||
```
|
||||
|
||||
### Disable Code Signing (no certificate)
|
||||
|
||||
```json
|
||||
"win": {
|
||||
"target": ["nsis", "portable"],
|
||||
"icon": "assets/icon.ico",
|
||||
"signAndEditExecutable": false,
|
||||
"sign": null
|
||||
}
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build:win
|
||||
# Output: dist/*.exe, dist/*.msi
|
||||
```
|
||||
|
||||
### Full Build-to-Deploy Workflow (AtomK Desktop)
|
||||
|
||||
```bash
|
||||
# 1. Version bump → branch → PR → merge (Gitea main is protected)
|
||||
cd /path/to/project
|
||||
npm version 3.9.XX --no-git-tag-version
|
||||
git checkout -b release/v3.9.XX
|
||||
git add package.json && git commit -m "build: bump version to 3.9.XX"
|
||||
git push origin release/v3.9.XX
|
||||
|
||||
# 2. Create PR + merge via Gitea API (basic auth, token unreliable)
|
||||
python3 -c "
|
||||
import requests, base64
|
||||
auth = base64.b64encode(b'USER:PASS').decode()
|
||||
r = requests.post('https://gitea.HOST/api/v1/repos/OWNER/REPO/pulls',
|
||||
headers={'Authorization': f'Basic {auth}', 'Content-Type': 'application/json'},
|
||||
json={'title':'build: bump to X.XX','head':'release/v3.9.XX','base':'main'}, verify=False)
|
||||
pr = r.json()['number']
|
||||
requests.post(f'.../pulls/{pr}/merge', headers={'Authorization': f'Basic {auth}'}, json={'Do':'merge'}, verify=False)
|
||||
"
|
||||
|
||||
# 3. Pull main + build
|
||||
git checkout main && git pull origin main
|
||||
rm -rf dist/
|
||||
NODE_OPTIONS=--max-old-space-size=4096 npm run build:win
|
||||
|
||||
# 4. Upload to Tencent COS (Hong Kong region)
|
||||
source ~/.hermes/custom_services.env
|
||||
coscmd -b 9websclub-1251422183 -r ap-hongkong upload dist/*.exe desktop/
|
||||
coscmd -b 9websclub-1251422183 -r ap-hongkong upload dist/*.exe.blockmap desktop/
|
||||
|
||||
# 5. Clean up
|
||||
git branch -d release/v3.9.XX
|
||||
git push origin --delete release/v3.9.XX
|
||||
```
|
||||
|
||||
### Key Pitfalls
|
||||
|
||||
1. **Disk space** — 300MB+ per build; clean old builds before new ones
|
||||
2. **Wine warnings** — wine32 display driver warnings are harmless for CLI usage
|
||||
3. **COS upload** — use `coscmd` for Tencent Cloud (configured via `~/.hermes/custom_services.env`), `aws s3` for AWS
|
||||
4. **Code signing** — without a certificate, set `signAndEditExecutable: false` and `sign: null`
|
||||
5. **Gitea protected branches** — `main` is usually protected; push to `release/vX.X.XX` branch instead, then create + merge PR via Gitea API. Use basic auth (username:password base64) — token may be expired.
|
||||
|
||||
**See:** `references/electron-cross-compile.md` for full step-by-step, NSIS config, and upload procedures.
|
||||
|
||||
## Section 2: Bundled Chromium DLL Fix on Windows
|
||||
|
||||
When bundling Chromium inside an Electron app for CDP/browser automation, 3 GPU DLLs must be present or Chromium crashes silently on Windows.
|
||||
|
||||
### Problem
|
||||
|
||||
Electron apps bundling Chromium fail silently with no error output. Root cause: GPU-related DLLs were removed to reduce installer size, but Chromium requires them even with `--disable-gpu`.
|
||||
|
||||
### Missing DLLs
|
||||
|
||||
Copy these from a matching Chromium for Windows release:
|
||||
- `D3DCompiler_47.dll` (~4.9MB)
|
||||
- `libEGL.dll` (~494KB)
|
||||
- `libGLESv2.dll` (~8.2MB)
|
||||
|
||||
Source: `https://storage.googleapis.com/chromium-browser-snapshots/Win/<build>/chrome-win.zip`
|
||||
|
||||
### Key Insight
|
||||
|
||||
**`--disable-gpu` is NOT sufficient.** Chromium still loads these DLLs at startup for basic rendering pipeline initialization.
|
||||
|
||||
### Fix Steps
|
||||
|
||||
1. Download matching Chromium version full archive
|
||||
2. Copy 3 DLLs to bundled chromium directory (e.g., `resources/chromium/`)
|
||||
3. Remove `--disable-gpu` flag from spawn args (now GPU works properly)
|
||||
4. Add `diagnoseBrowserSearch()` function: check registry paths, known paths, DLL presence
|
||||
5. Rebuild: `npm run build:win`
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
7z l dist/app-X.X.X-setup.exe | grep -E "D3DCompiler|libEGL|libGLESv2"
|
||||
```
|
||||
|
||||
**See:** `references/electron-bundled-chromium-dll-fix.md` for full diagnosis and fix details.
|
||||
Reference in New Issue
Block a user