vscode调试electron必须配齐四要素：node.js v20.14.0 + electron ≥38.1.2、本地安装electron、launch.json双配置（主进程node+渲染进程pwa-chrome）、eslint按环境区分；缺一则断点灰、ipc失效或白屏。
VSCode本身不内置Electron开发支持，必须手动配齐 Node.js 版本、本地 Electron 安装、launch.json 双进程调试配置、ESLint 环境区分这四块，缺一不可——否则断点灰掉、ipcRenderer 报错、openDevTools() 白屏都是常态。
Node.js 和 Electron 版本必须严格匹配
当前最稳组合是 Node.js v20.14.0 + Electron ≥38.1.2。v22+ 会直接触发 ERR_MODULE_NOT_FOUND；v16 或更早则报 DEP0148 警告并让 IPC 失效。
- 用
nvm install 20.14.0 && nvm use 20.14.0切换版本，再执行node -v和npm -v验证（npm ≥9.5.0） - 项目内必须
npm install electron --save-dev，禁用npm install -g electron——全局安装会导致require('electron')找不到模块 - Electron 官方镜像建议设为
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/，写入.npmrc避免安装卡死
launch.json 必须拆成两个独立调试配置
VSCode 不支持单条配置同时 attach 主进程和渲染进程。主进程走 node 类型，渲染进程必须用 pwa-chrome 类型，且启动顺序不能颠倒：先跑主进程，等窗口出现后再 attach 渲染进程。
- 主进程配置关键项：
"type": "node"，"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron"（Windows 加.cmd后缀），"args": ["."]；漏掉"autoAttachChildProcesses": true会导致新BrowserWindow实例无法被断点捕获 - 渲染进程配置关键项：
"type": "pwa-chrome"，"request": "attach"，"port": 9222；主进程里需在'ready-to-show'事件后调用win.webContents.openDevTools({ mode: 'detach' }) -
--inspect=9229若加在args中，必须放在"."前面，否则 Electron 直接忽略
ESLint 必须按进程环境区分规则
主进程是纯 Node.js 环境，不能用 document、window；渲染进程虽有 DOM，但若启用 contextIsolation: true（推荐），就无法直接访问 require 或 process。ESLint 若不区分，会批量误报或漏报安全风险。
- 在
.eslintrc.cjs中为不同文件设置env：env: { node: true }用于main.js、preload.js；env: { browser: true, es2021: true }用于renderer.js或 Vue/React 组件 - 渲染进程需显式声明
ipcRenderer全局变量，加globals: { ipcRenderer: 'readonly' }消除no-undef误报 - Preload 脚本中必须用
const { contextBridge, ipcRenderer } = require('electron')显式桥接，否则contextIsolation下 IPC 会静默失败
常见白屏/断点失效的底层原因
很多“配置看起来都对但就是不工作”的问题，根源在模块系统冲突或路径映射错位。比如你用 ES Module 写 main.js（含 import），但 Electron 主进程默认以 CommonJS 加载，app 就可能为 undefined；又或者 sourceMapPathOverrides 没配准，TypeScript 或打包后的源码断点根本不会命中。
- 若用 Vite/Electron 构建，
main.js不能直接写import，得加"type": "module"到package.json，或改用createRequire兼容 CommonJS -
sourceMaps在纯 JS 项目里可删，否则错误的outFiles路径会让调试器放弃映射 - 务必在终端运行
ELECTRON_ENABLE_LOGGING=true npm start，看日志里有没有Failed to load preload script或Cannot find module—— 这比盲调快十倍
