Electron API 速查与配置模板（2025 年最新版）
以下是 Electron 开发中最常用 API 的快速参考表，以及生产级项目推荐的标准配置模板（基于 Electron 33+，Chromium 128+）。
1.核心模块速查表
| 模块 | 常见 API | 用途与示例 |
|---|---|---|
| app | app.whenReady()app.getPath(name)app.setLoginItemSettings()app.on('window-all-closed') | 应用生命周期、路径获取、开机启动 示例： app.getPath('userData')获取配置目录 |
| BrowserWindow | new BrowserWindow(options)win.loadURL()win.webContents.openDevTools() | 创建窗口、加载内容、调试 |
| ipcMain | ipcMain.handle(channel, handler)ipcMain.on(channel, listener) | 主进程接收渲染进程消息（推荐 handle 用于异步） |
| ipcRenderer | ipcRenderer.invoke(channel, args)ipcRenderer.send(channel, args) | 渲染进程向主进程通信 |
| session | ses.cookies.get/setses.setPermissionRequestHandler()ses.fetch() | Cookie 管理、权限控制、自定义网络请求 |
| net | net.request()net.fetch()(Electron 25+) | 主进程 HTTP/HTTPS 请求（支持系统代理） |
| safeStorage | safeStorage.encryptString/decryptString() | 系统级加密（密钥链/Keychain） |
| nativeImage | nativeImage.createFromPath() | 系统托盘图标、任务栏图标 |
| Tray | new Tray(image)tray.setContextMenu() | 系统托盘 |
| Menu | Menu.setApplicationMenu()Menu.buildFromTemplate() | 应用菜单、右键菜单 |
| dialog | dialog.showOpenDialog()dialog.showMessageBox() | 文件选择、消息弹窗 |
| shell | shell.openExternal(url) | 安全打开外部链接 |
| powerMonitor | powerMonitor.on('suspend') | 系统休眠/唤醒监听 |
| autoUpdater | autoUpdater.checkForUpdates() | 自动更新（需配合 electron-updater） |
2.生产级 BrowserWindow 配置模板
// main.jsconst{app,BrowserWindow,session}=require('electron');constpath=require('path');functioncreateWindow(){constwin=newBrowserWindow({width:1200,height:800,minWidth:800,minHeight:600,show:false,// 先隐藏，ready-to-show 再显示（防白屏）icon:path.join(__dirname,'build/icon.ico'),// 跨平台图标webPreferences:{preload:path.join(__dirname,'preload.js'),// 必须contextIsolation:true,// 必开（默认 true）nodeIntegration:false,// 必关sandbox:true,// 强烈推荐（渲染进程沙盒）webSecurity:true,// 必开allowRunningInsecureContent:false,experimentalFeatures:false,// backgroundThrottling: false, // 若需后台保持活跃可关闭},backgroundColor:'#fff',// 与前端首屏颜色一致titleBarStyle:'default',// macOS: 'hiddenInset' 可自定义标题栏trafficLightPosition:{x:12,y:12},// macOS 交通灯位置});// 生产环境加载打包后的文件，开发环境加载 Vite 服务器if(process.env.NODE_ENV==='development'){win.loadURL('http://localhost:5173');win.webContents.openDevTools({mode:'detach'});}else{win.loadFile(path.join(__dirname,'dist/index.html'));}win.once('ready-to-show',()=>win.show());// 安全：阻止新窗口弹出，改为浏览器打开win.webContents.setWindowOpenHandler(({url})=>{shell.openExternal(url);return{action:'deny'};});// 安全：阻止导航到外部win.webContents.on('will-navigate',(e,url)=>{if(!url.startsWith('file:')&&!url.includes('localhost')){e.preventDefault();shell.openExternal(url);}});returnwin;}app.whenReady().then(()=>{createWindow();app.on('activate',()=>{if(BrowserWindow.getAllWindows().length===0)createWindow();});});app.on('window-all-closed',()=>{if(process.platform!=='darwin')app.quit();});3.安全 preload.js 模板（contextBridge）
// preload.jsconst{contextBridge,ipcRenderer}=require('electron');contextBridge.exposeInMainWorld('electronAPI',{// 推荐：白名单渠道invoke:(channel,...args)=>{constvalidChannels=['get-data','save-file','open-dialog'];if(validChannels.includes(channel)){returnipcRenderer.invoke(channel,...args);}thrownewError(`Invalid channel:${channel}`);},on:(channel,listener)=>{constvalidChannels=['update-available','download-progress'];if(validChannels.includes(channel)){ipcRenderer.on(channel,listener);}},removeAllListeners:(channel)=>ipcRenderer.removeAllListeners(channel),});4.package.json 关键配置模板（electron-builder）
{"build":{"appId":"com.yourcompany.yourapp","productName":"YourApp","directories":{"output":"dist-electron"},"files":["dist/**/*","main/**/*","preload.js"],"extraResources":[{"from":"resources/","to":"resources","filter":["**/*"]}],"win":{"target":["nsis","portable"],"icon":"build/icon.ico"},"mac":{"target":["dmg","zip"],"icon":"build/icon.icns","hardenedRuntime":true,"gatekeeperAssess":false},"linux":{"target":["AppImage","deb"],"icon":"build/icons"},"publish":[{"provider":"github","owner":"yourname","repo":"yourapp"}]}}这些模板已集成当前最佳实践（沙盒 + 上下文隔离 + Fuses + 安全 IPC）。直接复制到新项目中使用，几乎可直接用于生产。如果需要特定功能（如托盘、自动更新、原生菜单）的完整代码模板，告诉我，我可以继续补充！
