Electron跨平台需手动保障：避开Node.js/Chromium差异、正确处理路径权限、分平台构建；主进程用Node API，渲染进程禁用nodeIntegration，默认需preload脚本桥接IPC通信。
Electron 本身不提供“跨平台桌面应用”的自动保障，能否真正跨平台，取决于你是否避开 Node.js 和 Chromium 的行为差异、是否正确处理路径与权限、是否在打包时覆盖所有目标平台的构建配置。
Electron 主进程和渲染进程必须严格分离
主进程运行在 Node.js 环境中，可调用 fs、child_process、app、BrowserWindow 等 API；渲染进程默认禁用 Node.js 集成（出于安全），若需使用 require 或 process，必须显式启用 nodeIntegration: true 并配合 contextIsolation: false —— 但这是高危组合，现代项目应改用 preload 脚本桥接。
常见错误现象：
- 在渲染进程直接写
require('fs')报错require is not defined - 启用了
nodeIntegration却没关contextIsolation，导致require可用但process为空对象 - preload 脚本里漏写
contextBridge.exposeInMainWorld，导致渲染进程无法访问注入的方法
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 主进程只负责窗口生命周期、菜单、协议注册、IPC 监听
- 所有文件操作、系统调用、敏感逻辑封装进主进程，通过
ipcRenderer.invoke/ipcMain.handle通信 - preload 脚本中用
contextBridge.exposeInMainWorld('api', { readFile: () => ipcRenderer.invoke('read-file') })暴露受限接口
打包时必须为每个目标平台单独构建
electron-builder 或 electron-packager 不会自动交叉编译：在 macOS 上执行 build --win --linux 无法生成可用的 Windows/Linux 二进制，因为 Electron 的二进制依赖宿主机的工具链和签名机制。
使用场景：
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- CI/CD 中需用三台机器（macOS、Windows Server、Ubuntu）分别构建对应平台安装包
- 本地开发时，仅能构建当前操作系统的目标包（如 macOS 可打
.dmg和.zip，但不能生成.exe）
参数差异与坑点：
-
electron-builder的target配置中，nsis（Windows）、dmg（macOS）、deb（Linux）行为完全不同，比如nsis.allowToChangeInstallationDirectory默认为false，用户无法自选安装路径 - macOS 上未配置
identity（Apple Developer ID）会导致打包后应用无法启动（报错Library not loaded: @rpath/Electron Framework.framework/Electron Framework） - Linux 打包若未设置
category和desktop字段，生成的.deb安装后可能不显示在应用菜单
路径处理必须用 path.join + app.getPath，禁用字符串拼接
硬编码 './data/config.json' 或 'C:\Users\xxx\AppData\Roaming' 在跨平台时必然失败。不同系统路径分隔符、用户数据目录位置、可执行文件位置均不同。
正确做法：
- 用户数据存放在
app.getPath('userData')下，该路径在各平台自动映射到标准位置（macOS:~/Library/Application Support/YourApp，Windows:%APPDATA%\YourApp，Linux:~/.config/yourapp） - 拼接路径一律用
path.join(app.getPath('userData'), 'config.json')，不要用+或模板字符串 - 读取资源文件（如图片、HTML）优先用
file://协议 +app.getAppPath()，避免__dirname在打包后失效（ASAR 归档中__dirname指向 asar 内部路径）
性能影响：多次调用 app.getPath 无开销，它是同步缓存结果的；但误用 fs.readFileSync 读取 ASAR 外部路径会抛出 ENOENT，而不会静默失败。
Node.js 原生模块需重新编译，且仅限匹配目标 Electron 版本
Electron 使用定制版 Chromium 和特定版本的 Node.js（例如 Electron 28 对应 Node.js 20.9.x）。直接 npm install sqlite3 安装的是适配系统 Node 的二进制，加载时会报错：Error: The module '/path/binding.node' was compiled against a different Node.js version。
实操步骤必须包含：
- 安装
electron-rebuild - 执行
npx electron-rebuild -f -w sqlite3 -v 28.0.0 -p -t node（其中-v必须与你的 Electron 版本一致，-t node表示重建为 Node 模块而非 Electron 插件） - 若模块含 C++ 代码，还需确保对应平台装有 Python 3.10+、C++ 构建工具（Windows SDK / Xcode Command Line Tools / build-essential）
容易被忽略的一点：即使你只在主进程使用原生模块，也必须对它重建——渲染进程虽不加载，但打包工具（如 electron-builder）会扫描 node_modules 并尝试打包所有依赖，未重建的模块会在目标平台启动时报 MODULE_NOT_FOUND。
