VSCode需手动绑定项目级Node.js（v18.15.0–v20.14.0）与本地Electron（≥38.1.2），否则require('electron')报错、ipcRenderer undefined；launch.json须指定本地electron路径、--inspect=9229位置严格在"."前，并按进程环境区分ESLint规则。
VSCode 本身不识别 Electron 的 Node 环境，必须手动绑定项目级 Node.js 版本 + 本地 Electron 实例，否则 require('electron') 报错、ipcRenderer undefined、断点全灰都是必然结果。
Node.js 版本必须卡死在 v18.15.0–v20.14.0
Electron ≥38.1.2 声称支持 Node.js v20，但实测 v20.14.0 是当前唯一稳定上限；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 - Windows 用户注意：PowerShell 默认禁止脚本执行，需先运行
set-ExecutionPolicy RemoteSigned（管理员权限）
Electron 必须本地安装，且路径要写进 launch.json
全局安装（npm install -g electron）会导致 VSCode 启动的 Electron 和项目实际依赖的版本不一致——这是 require('electron') 找不到模块的最常见原因。
- 项目根目录执行：
npm install electron --save-dev -
launch.json中runtimeExecutable必须指向本地 bin："${workspaceFolder}/node_modules/.bin/electron"（Windows 加.cmd后缀） - 别用
electron命令字面量，也别用npx electron——它们不保证加载项目本地版本
launch.json 主进程配置必须带 --inspect=9229 且位置严格
Electron 12+ 对 --inspect 参数位置极其敏感：它必须出现在 .（即入口目录）之前，否则整个参数被忽略，VSCode 就 attach 不上主进程。
- 正确写法：
"args": ["--inspect=9229", "."] - 错误写法：
"args": [".", "--inspect=9229"]→ 断点永远不生效 - 加
"env": { "ELECTRON_ENABLE_LOGGING": "true" }，白屏时第一时间看到 IPC 初始化失败或窗口创建异常 - 删掉
sourceMaps和outFiles字段——纯 JS 项目不需要，加了反而干扰路径映射
ESLint 必须按进程环境区分规则
主进程是纯 Node.js 环境，渲染进程（尤其启用了 contextIsolation: true）不能直接访问 require 或 process；ESLint 若统一配置，要么批量误报，要么漏掉关键安全风险。
- 主进程文件（
main.js、preload.js）用：env: { node: true } - 渲染进程文件（
renderer.js、Vue/React 组件）用：env: { browser: true, es2021: true } - 渲染进程需显式声明：
globals: { ipcRenderer: 'readonly' }，否则no-undef误报 -
preload.js中必须用const { contextBridge, ipcRenderer } = require('electron')显式桥接，不能省略require
最容易被忽略的不是配置项本身，而是 Node.js 版本和 Electron 版本之间的隐式耦合——哪怕只差一个小版本号，ipcRenderer.invoke() 就可能返回 undefined 而不抛错，调试时得靠 ELECTRON_ENABLE_LOGGING 日志逐行确认初始化顺序。
