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