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

整体分为 5 大核心模块：

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

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

---

一、package.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

"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

运行

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

运行

// 软件初始化完成，唯一可以创建窗口的时机
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

运行

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

---

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

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

3.1 基础尺寸 & 位置

js

运行

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

运行

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

3.4 鼠标、键盘、菜单

js

运行

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

3.5 其他高级窗口配置

js

运行

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

---

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

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

js

运行

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

运行

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

运行

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

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

js

运行

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

---

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

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

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

# .env.development
NODE_ENV=development
VITE_DEV_SERVER_URL=http://localhost:5173

# .env.production
NODE_ENV=production

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

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

json

{
  "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"
    }
  ]
}

6.3 全局菜单配置 Menu

js

运行

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