Electron 全维度完整配置手册（最新稳定版，适配 Electron 25+）

前端逗比逗2026-07-28 14:53

整体分为 5 大核心模块：

  1. package.json 项目基础配置（入口、依赖、脚本、打包基础）
  2. 主进程 app 全局生命周期配置（全局系统参数）
  3. BrowserWindow 窗口全量配置（窗口外观、尺寸、行为）
  4. webPreferences 渲染进程安全 / 能力完整配置（重中之重）
  5. 打包配置（electron-builder 全参数）+ 调试 / 高级配置

适配之前的医疗病床桌面系统（录音、多窗口、Vue3、权限管控、CSP、音视频）。

一、package.json 顶层配置（项目根目录）

基础必填字段

json

json 复制代码 
{
  "name": "hospital-bed-system",
  "version": "1.0.0",
  "main": "./electron/main.js", // Electron入口文件，必须填写
  "description": "医院病床查房桌面系统",
  "author": "xxx",
  "license": "MIT",
  "homepage": "./",
  "private": true,
  "scripts": {
    "dev": "electron .", // 本地开发启动
    "build": "electron-builder", // 全平台打包
    "build-win": "electron-builder --win",
    "build-mac": "electron-builder --mac",
    "build-linux": "electron-builder --linux",
    "pack": "electron-builder --dir" // 打包绿色文件目录
  },
  "dependencies": {}, // 业务运行依赖（fs、path、录音、串口等放这里）
  "devDependencies": {
    "electron": "^30.0.0",
    "electron-builder": "^24.13.0"
  }
}

关键字段说明

表格

字段 说明
main 强制必填，主进程入口路径，不配置 Electron 无法启动
name 软件内部 ID，不能中文、空格，打包安装目录以此命名
version 版本号，升级更新依赖此版本
scripts 开发、打包命令，Windows/mac 通用

可选扩展配置

json

ruby 复制代码 
"electron-rebuild": {},
"type": "commonjs", // Electron默认commonjs；用ESModule改为module
"repository": { "type": "git", "url": "" },
"keywords": ["electron", "医疗", "查房", "录音"]

二、主进程 app 全局配置（main.js 内全局 API）

app 管控整个软件生命周期、系统权限、全局参数，所有配置写在主进程。

2.1 app 可配置属性（可读写）

表格

属性 类型 默认 作用
app.name string package.json name 修改应用系统显示名称
app.version string package.json version 只读，获取版本
app.userAgentFallback string Chromium 默认 全局 UA，适配内网接口、防盗链
app.accessibilitySupportEnabled boolean false 开启系统无障碍（屏幕阅读器），性能损耗大
app.applicationMenu Menu/null 系统默认菜单 全局替换顶部菜单栏；赋值null隐藏系统菜单栏
app.badgeCount number 0 Windows/mac 任务栏角标数字（未读床位提醒）
app.commandLine CommandLine - Chromium 底层命令行启动参数（最常用高级配置）

commandLine 高频配置（适配录音、硬件、音视频）

js

运行

javascript 复制代码 
const { app } = require('electron')
// 全局启动参数，必须写在app.whenReady()之前
app.commandLine.appendSwitch('disable-gpu-sandbox') // 解决Windows声卡、麦克风沙箱拦截
app.commandLine.appendSwitch('enable-speech-dispatcher') // 语音识别增强
app.commandLine.appendSwitch('allow-file-access-from-files') // 本地文件跨域
app.commandLine.appendSwitch('autoplay-policy', 'no-user-gesture-required') // 录音/音频自动播放无需点击
app.commandLine.appendSwitch('ignore-certificate-errors') // 内网HTTPS证书错误放行

2.2 app 全局生命周期事件（配置逻辑挂载点）

js

运行

dart 复制代码 
// 软件初始化完成，唯一可以创建窗口的时机
app.whenReady().then(async () => {})

// 全部窗口关闭
app.on('window-all-closed', () => {
  // macOS默认点关闭不退出，Windows直接退出
  if (process.platform !== 'darwin') app.quit()
})

// macOS点击Dock图标、无窗口时重建窗口
app.on('activate', () => {})

// 软件即将退出
app.on('before-quit', () => {
  // 查房录音收尾、保存音频、关闭麦克风
})

// 捕获所有web请求证书错误（内网必备）
app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  event.preventDefault()
  callback(true) // 信任内网自签证书
})

2.3 app 路径配置（统一资源目录）

js

运行

arduino 复制代码 
// 获取各类系统目录，用来存录音文件、日志、缓存
app.getPath('userData') // 软件持久化目录（录音缓存、床位配置）
app.getPath('desktop') // 桌面
app.getPath('documents') // 文档（推荐存放查房录音）
app.setPath('userData', 'D:/hospital/cache') // 自定义缓存目录

三、BrowserWindow 窗口完整配置（new BrowserWindow (options)）

完整分类清单，按使用优先级拆分，适配多病床窗口、双主题绿 / 蓝、白屏优化

3.1 基础尺寸 & 位置

js

运行

less 复制代码 
const mainWin = new BrowserWindow({
  // 尺寸
  width: 1400,
  height: 850,
  minWidth: 1000, // 最小宽度，防止卡片挤压错乱
  minHeight: 650,
  maxWidth: 2560,
  maxHeight: 1600,
  resizable: true, // 是否允许拖拽缩放窗口

  // 位置
  x: 200,
  y: 100,
  center: true, // 窗口屏幕居中，优先级高于x/y

  // 窗口显示控制（解决白屏）
  show: false, // 默认不渲染，页面加载完再显示
  backgroundColor: '#ffffff', // 底色，绿色模式#eaffef，查房蓝色#e6f0ff
})
// 页面完全渲染好再展示，杜绝白屏
mainWin.once('ready-to-show', () => {
  mainWin.show()
})

3.2 窗口外观、标题、图标、边框

表格

参数 类型 说明
title string 窗口标题，可动态修改win.setTitle()
icon string 窗口图标，必须 png/ico；Windows 用 ico，mac 用 icns
frame boolean false无边框窗口（自定义导航栏），默认 true
transparent boolean 窗口透明，配合 frame:false 做圆角
titleBarStyle default/hidden/hiddenInset mac 专用；hidden 隐藏标题栏、保留红绿灯
trafficLightPosition {x,y} mac 红绿灯按钮位置偏移
roundedCorners boolean Windows 窗口圆角开关

3.3 全屏、置顶、任务栏、行为控制

js

运行

yaml 复制代码 
fullscreen: false, // 全屏
fullscreenable: true, // 是否允许F11全屏
alwaysOnTop: false, // 窗口置顶（查房弹窗置顶）
skipTaskbar: false, // 不在任务栏显示
closable: true, minimizable: true, maximizable: true, // 按钮可用性
hasShadow: true, // 窗口阴影
movable: true, // 窗口能否拖动

3.4 鼠标、键盘、菜单

js

运行

yaml 复制代码 
disableAutoHideCursor: false,
autoHideMenuBar: true, // 按Alt才显示顶部菜单，默认隐藏（推荐）
menu: null, // 自定义当前窗口菜单；null=无菜单
kiosk: false, // 锁屏 kiosk 模式（医院触控屏可用）

3.5 其他高级窗口配置

js

运行

yaml 复制代码 
parent: null, // 父窗口（患者详情弹窗挂载主窗口）
modal: false, // 模态弹窗，锁住父窗口
webContentsPreferences: {}, // 全局web偏好兜底
paintWhenInitiallyHidden: true,
darkTheme: false, // 跟随系统深色模式

四、webPreferences 最全配置（Electron 安全核心，必细看，适配录音 / Vue/IPC）

完整字段 + 默认值 + 安全建议，分安全管控、Node 权限、音视频、网络、渲染、调试6 大类

js

运行

csharp 复制代码 
webPreferences: {
  // ========== 安全红线（生产环境严格遵守）==========
  nodeIntegration: false,
  // 禁止渲染页直接require Node；true有远程页面注入风险
  contextIsolation: true,
  // 上下文隔离，页面JS和preload彻底隔离，Electron官方强制推荐开启
  sandbox: true,
  // Chromium沙箱；开启后默认禁用nodeIntegration，Electron20+默认true
  webSecurity: true,
  // 开启同源策略；关闭会CORS全开，高危，内网调试临时关

  // ========== Node扩展权限（不推荐开启）==========
  nodeIntegrationInWorker: false, // WebWorker启用Node
  nodeIntegrationInSubFrames: false, // iframe启用Node
  enableRemoteModule: false, // 废弃remote模块，禁止使用，改用IPC

  // ========== Preload 预加载（唯一安全通信方案）==========
  preload: path.join(__dirname, './preload.js'),
  // 预加载脚本路径，所有主进程通信、麦克风权限、文件读写在这里暴露API

  // ========== 网络、跨域、证书、资源加载 ==========
  allowRunningInsecureContent: false,
  // 禁止HTTPS页面加载HTTP资源；内网接口必须开启则设true
  allowDisplayingInsecureContent: false,
  images: true, // 加载图片
  javascript: true, // 开启JS，前端项目必须true
  plugins: false, // 禁用Flash等插件
  defaultEncoding: 'UTF-8', // 默认编码，改成UTF-8避免乱码

  // ========== 音视频、录音、多媒体（适配查房语音录制）==========
  autoplayPolicy: 'no-user-gesture-required',
  // 音频自动播放策略：允许自动录音、播放，不用用户点击
  mediaControls: true, // 系统媒体快捷键
  disableHtmlFullscreen: false,
  imageAnimationPolicy: 'animate', // GIF: animate/animateOnce/noAnimation

  // ========== 缓存、会话、存储 ==========
  partition: 'persist:hospital',
  // 持久化session，多窗口共享cookie、localStorage；不带persist=内存临时存储
  session: null, // 优先级高于partition，自定义session对象
  spellcheck: false, // 关闭拼写检查，减少性能消耗
  zoomFactor: 1.0, // 页面缩放比例

  // ========== 硬件、渲染、GPU ==========
  webgl: true,
  backgroundThrottling: false,
  // 窗口后台时不限制定时器；查房后台录音必须关闭节流，防止录音中断
  offscreen: false, // 离屏渲染（截图、录屏用）

  // ========== 调试、开发配置 ==========
  devTools: process.env.NODE_ENV === 'development',
  // 生产环境直接禁用开发者工具，杜绝篡改
  experimentalFeatures: false, // 关闭Chromium实验特性
  enableWebSQL: false, // 废弃WebSQL禁用
}

4.1 医疗系统推荐安全最佳组合（固定照抄）

js

运行

yaml 复制代码 
webPreferences: {
  nodeIntegration: false,
  contextIsolation: true,
  sandbox: true,
  webSecurity: true,
  backgroundThrottling: false,
  autoplayPolicy: "no-user-gesture-required",
  preload: path.join(__dirname, "preload.js")
}

所有麦克风录音、文件读写、IPC 调用全部在 preload 用contextBridge暴露：

js

运行

javascript 复制代码 
// preload.js
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('electronAPI', {
  startRecord: () => ipcRenderer.invoke('record-start'),
  stopRecord: () => ipcRenderer.invoke('record-stop')
})

4.2 内网调试临时配置（仅开发，打包必须改回安全配置）

js

运行

vbnet 复制代码 
// 开发Vue方便调试，打包一定要复原
nodeIntegration: true,
contextIsolation: false,
sandbox: false,
webSecurity: false

五、electron-builder 打包完整配置（package.json 顶层 build 字段）

Windows、macOS、Linux 全平台参数，适配医院内网打包、图标、安装路径、权限

json

json 复制代码 
"build": {
  "appId": "com.hospital.bedsystem",
  "productName": "病床查房管理系统", // 安装包显示中文名
  "files": [
    "electron/**/*",
    "dist/**/*",
    "node_modules/**/*"
  ],
  "extraResources": [
    "./assets/**"
  ],
  "directories": {
    "output": "release", // 打包输出目录
    "buildResources": "build" // 图标资源目录
  },
  "asar": true, // 代码打包asar加密；false可解压源码
  "asarUnpack": ["node_modules/ffmpeg/**"], // 音视频依赖不解压

  // Windows专属配置
  "win": {
    "target": [
      {
        "target": "nsis", // 安装包；可选portable便携包
        "arch": ["x64"]
      }
    ],
    "icon": "build/icon.ico",
    "requestExecutionLevel": "asInvoker", // 权限：administrator管理员
    "publisherName": "医院信息科"
  },
  "nsis": {
    "oneClick": false, // 不要一键安装，允许选择安装路径
    "allowToChangeInstallationDirectory": true,
    "installerIcon": "build/icon.ico",
    "uninstallerIcon": "build/icon.ico",
    "shortcutName": "病床查房系统",
    "createDesktopShortcut": true,
    "createStartMenuShortcut": true
  },

  // Mac配置
  "mac": {
    "target": ["dmg", "zip"],
    "icon": "build/icon.icns",
    "hardenedRuntime": true,
    "entitlements": "build/entitlements.mac.plist",
    "entitlementsInherit": "build/entitlements.mac.plist"
  },

  // Linux
  "linux": {
    "target": ["deb", "rpm"],
    "icon": "build/icon.png",
    "category": "Utility"
  },

  // 自动更新
  "publish": [
    {
      "provider": "generic",
      "url": "http://内网服务器/update/"
    }
  ]
}

六、配套常用配置文件清单

6.1 .env 环境变量区分开发 / 生产

env

ini 复制代码 
# .env.development
NODE_ENV=development
VITE_DEV_SERVER_URL=http://localhost:5173

# .env.production
NODE_ENV=production

主进程读取环境变量区分是否打开调试工具、是否放开跨域。

6.2 .vscode/launch.json Electron 调试完整配置

json

bash 复制代码 
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "调试Electron主进程",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/electron/dist/electron.exe"
      },
      "args": ["."],
      "console": "integratedTerminal",
      "sourceMaps": true,
      "envFile": "${workspaceFolder}/.env.development"
    }
  ]
}

js

运行

less 复制代码 
const { Menu } = require('electron')
// 清空默认菜单
Menu.setApplicationMenu(null)
// 自定义极简菜单（只保留刷新、开发者工具）
const template = [  {    label: '视图',    submenu: [      {role: 'reload', label:'刷新'},      {role: 'toggleDevTools', label:'开发者工具'}    ]
  }
]
const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

七、针对病床查房系统定制专属配置汇总

1. 录音必开配置

  • backgroundThrottling: false 后台不停录
  • autoplayPolicy: no-user-gesture-required 无交互自动收音
  • 命令行关闭声卡沙箱 disable-gpu-sandbox
  • 录音文件路径统一指向 app.getPath('documents')/hospital-record

2. 双主题绿 / 蓝适配

  • 全局 CSS 变量控制颜色，Electron 无需改配置，仅通过 JS 全局状态切换 class
  • 窗口backgroundColor跟随模式动态修改 win.setBackgroundColor()

3. 多窗口（主列表 + 患者详情）

  • 详情窗口配置 parent: mainWin, modal: true 模态弹窗
  • 所有窗口共用一套 webPreferences 保证权限一致

4. 内网兼容配置

  • 开启证书忽略 app.on('certificate-error')
  • 必要时开启 allowRunningInsecureContent: true
  • 配置 UA 适配老旧内网接口

5. 安全硬性约束

  • 生产永远关闭nodeIntegration，所有通信走 IPC+preload
  • 生产禁用 DevTools，防止患者数据被控制台篡改

八、配置排查速查表

  1. 麦克风无法收音：检查sandbox、commandLine 声卡参数、autoplayPolicy
  2. Vue 页面 require 报错：安全三配置（nodeIntegration/contextIsolation/sandbox）冲突
  3. 后台录音断流：backgroundThrottling必须 false
  4. 本地文件跨域报错：allow-file-access-from-files命令行开关
  5. 打包后白屏：路径必须用path.resolve、asar 打包资源路径正确
  6. IPC 通信失败：上下文隔离，只能在 preload 调用 ipcRenderer
相关推荐
xiaobaoyu3 小时前
聊天问答文字逐步显示实现
前端
随风一样自由4 小时前
【前端+项目分析】`img` vs `Image`：从两个真实项目看前端图片组件的正确选择
前端·image·img·项目对比分析
倾颜4 小时前
断线之后，不要重跑 AI：在 POST + NDJSON 中实现可恢复 Agent 流
前端·后端·agent
程序员黑豆4 小时前
鸿蒙应用开发之父子组件传参：@Prop 装饰器使用教程
前端·后端·harmonyos
信也科技布道师4 小时前
从绝对定位到可维护页面：一次 MasterGo 还原链路的实战复盘
前端
程序员黑豆4 小时前
鸿蒙应用开发之V2状态管理：@Local、@ObservedV2、@Trace 使用教程
前端·后端·harmonyos
锻炼²4 小时前
Edge 地址栏搜索被其他浏览器劫持
前端·edge
Slice_cy4 小时前
Mint 自研框架设计与实现：从重复开发走向配置驱动（三）
前端·后端·架构
JoyT4 小时前
Nuxt 3的核心设计与静态官网应用
前端·javascript·vue.js
热门推荐
01GitHub 镜像站点02如何新建文件夹？ 电脑新建文件夹的4种方法032026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片04国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）05AI科技热点日报 | 2026年07月01日06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新092026 年 AI 大模型 & AI 编程工具实战全总结10CC-Switch & Claude 基于 Linux 服务器安装使用指南