From 65576af0f7b8cf54442f41fc4df63eb5f8c9de29 Mon Sep 17 00:00:00 2001 From: admin9webs Date: Fri, 10 Jul 2026 16:10:51 +0800 Subject: [PATCH] Add archived/electron-cross-compile --- .../archived/electron-cross-compile/SKILL.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 skills/archived/electron-cross-compile/SKILL.md diff --git a/skills/archived/electron-cross-compile/SKILL.md b/skills/archived/electron-cross-compile/SKILL.md new file mode 100644 index 0000000..f6d3a70 --- /dev/null +++ b/skills/archived/electron-cross-compile/SKILL.md @@ -0,0 +1,128 @@ +--- +name: electron-cross-compile +description: Cross-compile Electron desktop apps for Windows (exe/msi) on a Linux server. Covers wine setup, code signing bypass, disk space pitfalls, and COS upload for delivery. +tags: [electron, windows, cross-compile, nsis, portable, exe, msi, wine] +--- + +# 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) + +```bash +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: + +```json +"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) + +```python +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 + +```bash +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:** + +```bash +# 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 + +```bash +# 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 + +1. **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. +2. **Wine display driver errors**: `nodrv_CreateWindow` errors are harmless — wine works for CLI signing steps without X11. +3. **`sign: false` vs `sign: null`**: `false` is ignored by electron-builder; must use `null` to fully skip signing. +4. **`extraResources` paths**: Relative paths like `../extension` are resolved from the `package.json` directory. Missing source dirs cause silent failures. +5. **No code signing = SmartScreen warning**: Windows users will see "Unknown publisher" — instruct them to click "More info" → "Run anyway". +6. **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. +7. **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. +8. **🔥 `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