仅靠 index.html 无法构建可运行的 Electron 应用，它只是渲染层的一部分；必须配合 main.js（主进程）和正确的 package.json 配置才能启动，否则双击或执行 npm start 会报错或直接退出。
直接说结论：仅靠 index.html 无法构建可运行的 Electron 应用，它只是渲染层的一部分；必须配合 main.js（主进程）和正确的 package.json 配置才能启动，否则双击或执行 npm start 会报错或直接退出。
为什么 index.html 单独打开只是网页，不是桌面应用
Electron 不是“把 HTML 打包成 exe”那么简单。它需要一个运行时环境来创建窗口、管理生命周期、桥接 Node.js 能力。index.html 在 Electron 中只充当「渲染进程」的内容源——类似浏览器里打开的页面，但没浏览器壳子、没进程控制、也没系统权限。
- 直接双击
index.html：走的是系统默认浏览器，完全脱离 Electron 运行时，require('electron')或fs等 Node 模块会报ReferenceError: require is not defined - 没
main.js：Electron 启动时找不到入口，报错App threw an error during load: Error: Cannot find module './main.js' -
webPreferences配置缺失（比如没开nodeIntegration或没设preload）：即使窗口弹出来，JS 也无法调用 Node API，fs.readFile会失败
index.html 在 Electron 里的正确用法
它本质是一个静态资源文件，由 BrowserWindow 加载，加载方式决定能力边界：
- 用
win.loadFile('index.html')：推荐开发初期使用，路径为相对项目根目录，支持本地文件协议（file://），但注意：若启用了contextIsolation: true（Electron 12+ 默认），必须配preload脚本才能安全暴露 API - 用
win.loadURL('http://localhost:3000')：适合配合 Vite/React/Vue 开发服务器，热更新友好，但打包后不可用，需切换回loadFile - 避免写死绝对路径：如
file:///Users/xxx/index.html—— 跨平台失效，Windows 路径格式不同 - 不要在
index.html里直接requireNode 模块：浏览器环境不支持，会报错；所有原生能力必须经主进程或 preload 中转
常见错误：从 index.html 开始就踩坑
很多新手照着“Hello World”教程复制完 index.html 就以为成了，结果 npm start 报错或白屏。典型问题包括：
立即学习“前端免费学习笔记（深入）”；
-
Failed to load resource: net::ERR_FILE_NOT_FOUND：路径写错，比如mainWindow.loadFile('src/index.html')但文件实际在根目录 - 窗口弹出但空白，控制台报
Uncaught ReferenceError: require is not defined：webPreferences.nodeIntegration关闭了，又没配preload，导致渲染进程 JS 无法访问 Node - macOS 下关掉窗口后图标还在 Dock：没处理
app.on('window-all-closed')，尤其process.platform === 'darwin'时不能直接app.quit() - 打包后
index.html加载的图片/CSS 路径 404：用path.join(__dirname, 'assets', 'logo.png')替代相对路径，或统一用asset目录 +loadFile的路径解析逻辑
真正关键的不是 index.html 写得多漂亮，而是它被谁加载、以什么权限加载、以及主进程是否准备好承接它的请求。跨平台能跑起来的第一步，永远是让 main.js 成功创建窗口并稳定加载这个 HTML —— 其他都是后续优化的事。
