.electron-vue 构建后窗口白屏，控制台无报错，如何排查？

Question

.electron-vue 构建后白屏且控制台无报错，是典型「资源路径或加载时机」问题。常见原因：① `index.html` 中静态资源（如 `js/chunk-*.js`）路径为相对路径（`./`），构建后因 Electron 加载协议为 `file://`，导致路径解析失败；② `vue-router` 使用 `history` 模式未配置 `base` 或 `webPreferences.webSecurity: false` 未启用（影响本地文件读取）；③ 主进程未正确设置 `win.loadFile('dist/electron/index.html')`（而非 `loadURL('file://...')` 时路径拼接出错）；④ `background.js` 中 `mainWindow.webContents.openDevTools()` 被注释，掩盖了静默加载错误（建议临时启用并勾选「Preserve log」）。排查优先级：检查 `dist/electron/index.html` 中 script/src 是否为绝对路径（应以 `/` 开头或使用 `__dirname` 动态注入）；验证 `package.json` 的 `main` 入口与实际构建输出结构一致；用 `win.webContents.on('did-fail-load', ...)` 捕获底层加载失败事件。

Answer 1

```html

一、现象层：白屏无报错——表象即线索

Electron-Vue 构建后启动仅显示空白窗口，DevTools 控制台「Console」与「Network」标签页均无显式错误（HTTP 404/JS SyntaxError 等），但页面完全无渲染。这是典型的「静默失败」（Silent Failure）——非逻辑崩溃，而是资源加载链在底层被中断。关键信号在于：白屏 ≠ 代码未执行，而是 Vue 实例未挂载、Router 未初始化、或静态资源根本未加载成功。

二、路径层：file:// 协议下的 URL 解析陷阱

• dist/electron/index.html 中的 <script src="./js/app.js"> 在浏览器中解析为 file:///path/to/dist/electron/js/app.js，但在 Electron 中，./ 相对路径会因 file:// 协议缺乏上下文根而失效（尤其跨目录加载时）；
• 验证方法：手动打开该 HTML 文件（双击），若能正常运行，则证明是 Electron 加载方式问题；若也白屏，则确认为构建路径配置缺陷；
• 根治方案：在 vue.config.js 中强制设置 publicPath: './'（开发期）或 publicPath: '/'（生产期），并确保 output.publicPath 与之严格一致。

三、路由层：history 模式在 file:// 下的双重约束

配置项	必需性	说明
base: process.env.NODE_ENV === 'production' ? './' : '/'	✅ 强烈建议	适配 file:// 协议下相对路径基准，避免 router.push('/home') 解析为 file:///home
webPreferences: { webSecurity: false }	⚠️ 临时调试必开	关闭同源策略后，fetch('./api/data.json') 等本地文件读取才可能成功

四、加载层：loadFile vs loadURL 的语义鸿沟

主进程应使用 win.loadFile(path.join(__dirname, 'dist/electron/index.html')) 而非 win.loadURL('file://' + path.resolve(...) + '/index.html')。后者易因路径拼接错误（如 Windows 反斜杠未转义、空格未 encode）导致协议解析失败，且无法触发 did-fail-load 事件。以下为健壮加载模式：

const indexPath = path.join(__dirname, 'dist', 'electron', 'index.html');
if (!fs.existsSync(indexPath)) {
  console.error('❌ Critical: index.html not found at', indexPath);
}
win.loadFile(indexPath); // ✅ 原生路径安全解析

五、诊断层：启用「可见的沉默」——捕获 did-fail-load

在创建 BrowserWindow 后立即注册监听器，将隐性失败显性化：

win.webContents.on('did-fail-load', (event, errorCode, errorDescription, validatedURL) => {
  console.error('[Electron Load Fail]', { errorCode, errorDescription, validatedURL });
  // 示例输出：errorCode=-300（net::ERR_FILE_NOT_FOUND）
});

同时务必取消注释 mainWindow.webContents.openDevTools({ mode: 'detach' })，并在 DevTools 中勾选 Preserve log，否则页面重载后所有早期资源加载错误将被清空。

六、构建层：electron-vue 输出结构与 package.json 的契约一致性

检查 package.json 的 "main": "background.js" 是否指向正确入口；确认构建脚本（如 "build:electron": "vue-cli-service build --mode electron-builder"）输出目录是否与 loadFile() 路径严格匹配。常见错位：

• 构建输出到 dist_electron/，但代码仍读 dist/electron/；
• background.js 中 __dirname 指向 dist/ 根，而非 dist/electron/ 子目录；
• 使用 electron-builder 时，directories.output 配置覆盖了默认路径。

七、进阶验证：动态注入 __dirname 保障路径可靠性

在 background.js 中向渲染进程注入绝对基础路径：

win.webContents.on('dom-ready', () => {
  win.webContents.executeJavaScript(`
    window.__APP_BASE__ = 'file://' + require('path').join(${JSON.stringify(__dirname)}, '..');
  `);
});

随后在 index.html 中通过 <script>document.write('<script src="' + window.__APP_BASE__ + '/js/app.js"></script>')</script> 动态加载，彻底规避静态路径硬编码风险。

八、系统性排查流程图

graph TD
  A[启动白屏] --> B{DevTools 是否开启？}
  B -->|否| C[立即启用 openDevTools + Preserve log]
  B -->|是| D[检查 Network 标签：JS/CSS 是否 200？]
  D -->|404| E[检查 index.html 中 script/src 路径]
  D -->|200| F[检查 Vue Devtools 是否识别实例？]
  F -->|否| G[监听 did-fail-load & 检查 webSecurity]
  F -->|是| H[审查 router.beforeEach 是否阻塞]
  E --> I[修正 publicPath 或 loadFile 路径]
  G --> I

```