fix: the problem when developing on arm64 and container environments, update Electron version to 29.4.0 and add network interfaces fallback

- Updated Electron dependency from 19.1.9 to 29.4.0 in package.json and pnpm-lock.yaml.
- Added a new utility for handling network interfaces fallback in os-network-fallback.cjs and os-network-fallback.js.
- Updated README.md with instructions for Linux arm64 environments and additional notes on phantomjs configuration.
- Modified .npmrc to include a comment regarding phantomjs_skip_download.
- Refactored background.js to import the new network fallback utility.

Author: cute-omega

.npmrc

@@ -1 +1,3 @@
+# Enable it if phantomjs-prebuilt postinstall fails on some environments.
+# phantomjs_skip_download=true
 shamefully-hoist=true

README.md

@@ -136,10 +136,10 @@
 
 ### 2.2、开启前 vs 开启后
 
-|          | 开启前                         | 开启后                                            |
-| -------- | ------------------------------ | ------------------------------------------------- |
-| 头像     | ![](./doc/avatar2.png)         | ![](./doc/avatar1.png)                            |
-| clone    | ![](./doc/clone-before.png)    | ![](./doc/clone.png)                              |
+|          | 开启前                         | 开启后                                           |
+|----------|--------------------------------|--------------------------------------------------|
+| 头像     | ![](./doc/avatar2.png)         | ![](./doc/avatar1.png)                           |
+| clone    | ![](./doc/clone-before.png)    | ![](./doc/clone.png)                             |
 | zip 下载 | ![](./doc/download-before.png) | ![](./doc/download.png)秒下的，实在截不到速度的图 |
 
 ## 三、模式说明
@@ -386,6 +386,70 @@ npm install -g pnpm --registry=https://registry.npmmirror.com
 
 ```
 
+#### 3）Linux arm64 环境（Electron 安装提示）
+
+如果你在 Linux arm64 上为 GUI 安装依赖遇到 Electron `postinstall` 崩溃（`double free or corruption`）或无法下载二进制，可按下面流程处理：
+
+常见错误提示：
+- `phantomjs-prebuilt`: Unexpected platform or architecture: linux/arm64，postinstall 失败。
+- `electron` postinstall: double free or corruption (out) / Aborted (core dumped)。
+
+1. 使用与 Electron 安装脚本兼容的 Node 版本（建议 LTS 18）：
+
+```shell
+nvm install 18.20.8
+nvm use 18.20.8
+corepack enable
+```
+
+2. 正常安装 GUI 依赖（脚本需要开启）：
+
+```shell
+pnpm install --filter @docmirror/dev-sidecar-gui
+```
+
+3. 若依旧在下载阶段崩溃，可手动下载并解压 Electron 二进制：
+
+```shell
+electron_dir="$(pwd)/node_modules/.pnpm/[email protected]/node_modules/electron"
+rm -rf "$electron_dir/dist"
+curl -L --retry 3 --retry-delay 2 -o /tmp/electron-v29.4.6-linux-arm64.zip \
+  https://github.com/electron/electron/releases/download/v29.4.6/electron-v29.4.6-linux-arm64.zip
+unzip -q /tmp/electron-v29.4.6-linux-arm64.zip -d "$electron_dir/dist"
+if [ -f "$electron_dir/dist/electron.d.ts" ]; then mv "$electron_dir/dist/electron.d.ts" "$electron_dir/electron.d.ts"; fi
+printf 'electron' > "$electron_dir/path.txt"
+```
+
+4. 首次运行若提示 `chrome-sandbox` 权限问题，可在本地开发时关闭沙箱，或设置 SUID 权限：
+
+```shell
+# 开发/调试禁用沙箱（无需 root）
+ELECTRON_NO_SANDBOX=1 pnpm -F @docmirror/dev-sidecar-gui run electron:serve
+
+# 或为 chrome-sandbox 设置 SUID（需要 root）
+sudo chown root:root "$electron_dir/dist/chrome-sandbox"
+sudo chmod 4755 "$electron_dir/dist/chrome-sandbox"
+```
+
+> `.npmrc` 建议
+> - `phantomjs_skip_download=true`：避免旧版 `phantomjs-prebuilt` 在 arm64/容器环境拉取二进制导致安装失败，建议保留。
+
+#### 4）Termux/Android ARM64 运行 GUI（无 root）
+
+- 预加载网络接口兜底、强制关闭 Electron 沙箱（无需 root，使用 HOME 路径）：
+
+```bash
+cd $HOME/dev-sidecar/packages/gui
+NODE_OPTIONS="--require ${HOME:-/data/data/com.termux/files/home}/dev-sidecar/packages/gui/src/utils/os-network-fallback.cjs" \
+ELECTRON_FORCE_NO_SANDBOX=1 ELECTRON_NO_SANDBOX=1 ELECTRON_DISABLE_SANDBOX=1 \
+npm run electron
+```
+
+- 说明：
+  - Termux 缺少 setuid 能力，必须关闭沙箱，否则会提示 chrome-sandbox 权限错误。
+  - `os-network-fallback.cjs` 会在 `uv_interface_addresses` 权限受限时返回回环接口，避免 node-ipc 崩溃。
+  - 若仍需沙箱，只能在支持 setuid 的环境或 root 下运行。
+
 ### 8.2、开发调试模式启动
 
 运行如下命令即可开发模式启动

packages/gui/package.json

@@ -45,7 +45,7 @@
     "@vue/babel-preset-jsx": "^1.4.0",
     "@vue/cli-plugin-babel": "^5.0.8",
     "@vue/cli-service": "^5.0.8",
-    "electron": "^19.1.9",
+    "electron": "^29.4.0",
     "electron-builder": "^25.1.8",
     "electron-icon-builder": "^2.0.1",
     "json5-loader": "^4.0.1",
@@ -56,4 +56,4 @@
     "last 2 versions",
     "not dead"
   ]
-}
+}

packages/gui/src/background.js

@@ -1,5 +1,6 @@
 'use strict'
 /* global __static */
+import './utils/os-network-fallback'
 import path from 'node:path'
 import DevSidecar from '@docmirror/dev-sidecar'
 import { app, BrowserWindow, dialog, globalShortcut, ipcMain, Menu, nativeImage, nativeTheme, powerMonitor, protocol, Tray } from 'electron'
@@ -47,7 +48,7 @@ protocol.registerSchemesAsPrivileged([
   { scheme: 'app', privileges: { secure: true, standard: true } },
 ])
 
-function openDevTools () {
+function openDevTools() {
   try {
     log.debug('尝试打开 `开发者工具`')
     win.webContents.openDevTools()
@@ -57,7 +58,7 @@ function openDevTools () {
   }
 }
 
-function closeDevTools () {
+function closeDevTools() {
   try {
     log.debug('尝试关闭 `开发者工具`')
     win.webContents.closeDevTools()
@@ -67,7 +68,7 @@ function closeDevTools () {
   }
 }
 
-function switchDevTools () {
+function switchDevTools() {
   if (!win || !win.webContents) {
     return
   }
@@ -79,7 +80,7 @@ function switchDevTools () {
 }
 
 // 隐藏主窗口，并创建托盘，绑定关闭事件
-function setTray () {
+function setTray() {
   // const topMenu = Menu.buildFromTemplate({})
   // Menu.setApplicationMenu(topMenu)
   // 用一个 Tray 来表示一个图标,这个图标处于正在运行的系统的通知区
@@ -148,7 +149,7 @@ function setTray () {
   return appTray
 }
 
-function checkHideWin () {
+function checkHideWin() {
   const config = DevSidecar.api.config.get()
 
   // 配置为false时，不需要校验
@@ -170,7 +171,7 @@ function checkHideWin () {
   return true
 }
 
-function hideWin (reason = '', needCheck = false) {
+function hideWin(reason = '', needCheck = false) {
   if (win) {
     if (needCheck && !checkHideWin()) {
       return
@@ -186,7 +187,7 @@ function hideWin (reason = '', needCheck = false) {
   }
 }
 
-function showWin () {
+function showWin() {
   if (win) {
     win.show()
   } else {
@@ -198,13 +199,13 @@ function showWin () {
   winIsHidden = false
 }
 
-function changeAppConfig (config) {
+function changeAppConfig(config) {
   if (config.hideDockWhenWinClose != null) {
     hideDockWhenWinClose = config.hideDockWhenWinClose
   }
 }
 
-function createWindow (startHideWindow, autoQuitIfError = true) {
+function createWindow(startHideWindow, autoQuitIfError = true) {
   // Create the browser window.
   const windowSize = DevSidecar.api.config.get().app.windowSize || {}
 
@@ -361,11 +362,11 @@ function createWindow (startHideWindow, autoQuitIfError = true) {
   return true
 }
 
-async function beforeQuit () {
+async function beforeQuit() {
   log.info('before quit')
   return DevSidecar.api.shutdown()
 }
-async function quit (reason) {
+async function quit(reason) {
   log.info('app quit:', reason)
 
   if (tray) {
@@ -376,11 +377,11 @@ async function quit (reason) {
   app.quit()
 }
 
-function hasShortcut (showHideShortcut) {
+function hasShortcut(showHideShortcut) {
   return showHideShortcut && showHideShortcut.length > 1
 }
 
-function registerShowHideShortcut (showHideShortcut) {
+function registerShowHideShortcut(showHideShortcut) {
   globalShortcut.unregisterAll()
   if (hasShortcut(showHideShortcut)) {
     try {
@@ -407,7 +408,7 @@ function registerShowHideShortcut (showHideShortcut) {
   }
 }
 
-function initApp () {
+function initApp() {
   if (isMac) {
     app.whenReady().then(() => {
       app.dock.setIcon(path.join(__dirname, '../extra/icons/512x512-2.png'))

packages/gui/src/utils/os-network-fallback.cjs

@@ -0,0 +1,43 @@
+'use strict'
+
+const os = require('node:os')
+
+function installNetworkInterfacesFallback(logger = console) {
+    const logWarn = (logger && logger.warn) ? logger.warn.bind(logger) : console.warn
+
+    // Avoid double-patching
+    if (os.networkInterfaces && os.networkInterfaces.__dsPatched) {
+        return os.networkInterfaces
+    }
+
+    const originalNetworkInterfaces = os.networkInterfaces
+
+    const safeNetworkInterfaces = function networkInterfacesSafe() {
+        try {
+            return originalNetworkInterfaces.call(os)
+        } catch (err) {
+            logWarn('os.networkInterfaces failed, using fallback loopback stub:', err)
+            return {
+                lo: [
+                    {
+                        address: '127.0.0.1',
+                        netmask: '255.0.0.0',
+                        family: 'IPv4',
+                        mac: '00:00:00:00:00:00',
+                        internal: true,
+                        cidr: '127.0.0.1/8',
+                    },
+                ],
+            }
+        }
+    }
+
+    safeNetworkInterfaces.__dsPatched = true
+    os.networkInterfaces = safeNetworkInterfaces
+    return safeNetworkInterfaces
+}
+
+// Install immediately when required (for NODE_OPTIONS preload)
+installNetworkInterfacesFallback()
+
+module.exports = { installNetworkInterfacesFallback }

packages/gui/src/utils/os-network-fallback.js

@@ -0,0 +1,9 @@
+'use strict'
+
+import { createRequire } from 'node:module'
+import log from './util.log.gui'
+
+const require = createRequire(import.meta.url)
+const { installNetworkInterfacesFallback } = require('./os-network-fallback.cjs')
+
+installNetworkInterfacesFallback(log)

packages/mitmproxy/src/index.js

@@ -8,7 +8,7 @@ const { fireError, fireStatus } = require('./utils/util.process')
 let servers = []
 
 const api = {
-  async start (config) {
+  async start(config) {
     const proxyOptions = ProxyOptions(config)
     const setting = config.setting
     if (setting) {
@@ -47,7 +47,7 @@ const api = {
 
     registerProcessListener()
   },
-  async close () {
+  async close() {
     return new Promise((resolve, reject) => {
       if (servers && servers.length > 0) {
         for (const server of servers) {
@@ -77,7 +77,7 @@ const api = {
   },
 }
 
-function registerProcessListener () {
+function registerProcessListener() {
   process.on('message', (msg) => {
     log.info('child get msg:', JSON.stringify(msg))
     if (msg.type === 'action') {
@@ -111,9 +111,10 @@ function registerProcessListener () {
   process.on('exit', (code, signal) => {
     log.info('代理服务进程被关闭:', code, signal)
   })
-  process.on('beforeExit', (code, signal) => {
-    log.info('Process beforeExit event with code: ', code, signal)
-  })
+  // Aviod keeping print log before exit
+  // process.on('beforeExit', (code, signal) => {
+  //   log.info('Process beforeExit event with code: ', code, signal)
+  // })
   process.on('SIGPIPE', (code, signal) => {
     log.warn('sub Process SIGPIPE', code, signal)
   })