6.3 页面加载全流程：加载本地文件 / 远程页面、渲染生命周期

在 Electron 中，每个 BrowserWindow 都相当于一个独立的浏览器标签页。掌握如何加载内容、理解页面从创建到渲染完毕的生命周期，是构建稳定桌面应用的基础。本节会从实际开发的角度，梳理窗口加载本地文件与远程页面的方法，再详解渲染进程的关键生命周期事件。

6.3.1 加载本地文件

大多数 Electron 应用都会将前端资源打包在应用内部，然后通过 loadFile 加载本地的 HTML 入口文件。这是默认且推荐的方案，因为它保证了离线可用、启动速度快，同时避免了跨域问题。

const { app, BrowserWindow } = require('electron');
const path = require('path');

function createWindow() {
  const win = new BrowserWindow({
    width: 1000,
    height: 700,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,   // 保持开启，保证安全
      nodeIntegration: false,   // 关闭，不在渲染进程暴露 Node.js
    },
  });

  // 加载打包后的 index.html（假设放在 renderer 目录）
  win.loadFile(path.join(__dirname, 'renderer', 'index.html'));
}

app.whenReady().then(createWindow);

关键点：

loadFile 的参数必须是绝对路径，通常用 path.join(__dirname, ...) 拼接。
如果你的前端项目由 Webpack/Vite 构建，入口文件可能是 dist/index.html，记得打包后再运行 Electron。
本地文件访问不受跨域限制，但同样需要遵循 Content-Security-Policy 设置（通常在主进程或 HTML <meta> 标签中配置）。

6.3.2 加载远程页面

如果你需要嵌入一个线上页面（如公司内部系统、第三方网站），或者使用 localhost 的开发服务器进行热更新，可以用 loadURL。

// 开发环境加载 localhost
if (process.env.NODE_ENV === 'development') {
  win.loadURL('http://localhost:5173'); // Vite 默认端口
} else {
  win.loadFile(path.join(__dirname, 'dist', 'index.html'));
}

注意事项：

加载远程页面时，一定要在 webPreferences 中禁用 nodeIntegration，并开启 contextIsolation，以防恶意网站利用 Electron 权限。
远程页面可能有跨域限制，如果需要在其中使用 Electron API，应通过 preload 脚本桥接，而不是直接打开完整权限。
如果加载的是不可信的第三方站点，建议使用 <webview> 标签或保持在严格的沙箱环境中，尽量减少系统权限暴露。
对于生产环境，通常推荐使用本地加载，避免网络依赖和潜在的安全风险。

6.3.3 渲染进程的生命周期事件

BrowserWindow 的 webContents 提供了一系列事件，让你可以在页面加载的不同阶段插入逻辑。这些事件对于处理加载动画、错误重试、注入脚本等场景非常重要。

主要事件与触发顺序

did-start-loading：当 webContents 开始加载（显示 loading 转圈）时触发。
did-stop-loading：加载结束时触发（无论成功或失败）。
did-start-navigation：用户点击链接或者调用 loadURL/loadFile 导致导航开始时触发，可用于取消导航或做路由守卫。
dom-ready：文档 DOM 解析完成，还没开始加载图片、样式、脚本等外部资源。这是注入初始脚本的好时机。
did-finish-load：页面完全加载完毕，所有资源（图片、CSS、JS）都已加载成功。这时窗口内容应该是可交互的。
did-fail-load：页面加载失败（如网络错误、地址不存在）。通常用来显示错误界面或重试。

代码示例

const win = new BrowserWindow({ /* ... */ });

win.webContents.on('did-start-loading', () => {
  console.log('页面开始加载');
  // 可以在此显示加载动画，例如向渲染进程发送消息
});

win.webContents.on('dom-ready', () => {
  console.log('DOM 准备完毕');
  // 注入初始化代码
  win.webContents.executeJavaScript(`
    console.log('这段代码在 DOM ready 后执行');
  `);
});

win.webContents.on('did-finish-load', () => {
  console.log('页面加载完成');
  // 隐藏加载动画，通知渲染进程
  win.webContents.send('page-loaded');
});

win.webContents.on('did-fail-load', (event, errorCode, errorDescription, validatedURL) => {
  console.error('页面加载失败:', errorDescription);
  // 加载一个本地错误页面，或者显示对话框
  win.loadFile('error.html');
});

实用技巧

防止空白窗口闪烁：可以在创建窗口时设置 show: false，等到 did-finish-load 后再调用 win.show()，这样可以避免用户看到未渲染完成的白色页面。
加载动画：通过 IPC 在主进程监听到 did-start-loading 和 did-stop-loading，控制渲染进程显示或隐藏 loading 组件。
处理跳转：如果应用需要阻止某些外部链接在窗口内打开，可以监听 will-navigate 或 new-window 事件，然后用系统默认浏览器打开。
动态注入 CSS：利用 dom-ready 或 did-finish-load 配合 webContents.insertCSS 实现主题切换或样式覆写。
错误恢复：当 did-fail-load 触发时，可以尝试延迟重试（如加载本地缓存页面或提示用户检查网络）。

6.3.4 一个完整的加载流程示例

下面这个例子展示了从创建窗口到加载完成的全过程，包含了安全设置、本地/远程切换、加载状态响应以及错误处理：

const { app, BrowserWindow, dialog } = require('electron');
const path = require('path');

let mainWindow;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    show: false, // 不显示，等 ready-to-show
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
    },
  });

  // 开发模式用 Vite 服务器，生产模式用打包文件
  const isDev = !app.isPackaged;
  const startUrl = isDev
    ? 'http://localhost:5173'
    : `file://${path.join(__dirname, 'dist', 'index.html')}`;

  // 加载前显示原生加载指示器（可选）
  mainWindow.webContents.on('did-start-loading', () => {
    mainWindow.webContents.send('loading', true);
  });
  mainWindow.webContents.on('did-stop-loading', () => {
    mainWindow.webContents.send('loading', false);
  });

  // 页面加载失败时，回退到本地错误页
  mainWindow.webContents.on('did-fail-load', (event, errorCode, errorDescription, validatedURL) => {
    console.error(`Loading failed: ${errorDescription}`);
    // 如果是本地文件失败，可能是路径错误，按需处理
    mainWindow.loadFile(path.join(__dirname, 'fallback-error.html'));
  });

  // 页面一切就绪，显示窗口
  mainWindow.once('ready-to-show', () => {
    mainWindow.show();
    // 可在此聚焦窗口等
  });

  // 对外部链接的跳转，使用默认浏览器打开
  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
    require('electron').shell.openExternal(url);
    return { action: 'deny' };
  });

  // 加载入口
  if (isDev) {
    mainWindow.loadURL(startUrl);
    mainWindow.webContents.openDevTools(); // 开发环境下自动打开 DevTools
  } else {
    mainWindow.loadFile(path.join(__dirname, 'dist', 'index.html'));
  }
}

app.whenReady().then(createWindow);

这个示例中展示了几个重要实践：

利用 app.isPackaged 判断是否为打包后的生产环境，从而决定加载本地文件还是开发服务器。
使用 show: false 加 ready-to-show 事件消除白屏闪烁，ready-to-show 在首次绘制完成时触发，比 did-finish-load 更精确。
加载失败后加载一个本地错误页面，保证用户不会看到空白浏览器界面。
通过 setWindowOpenHandler 拦截外部链接，统一用系统浏览器打开，避免应用内导航到外部站点。

6.3.5 小结

页面加载是 Electron 应用的命脉，理解并善用加载方式与生命周期事件，能帮助你：

在正确的时间点执行初始化逻辑（dom-ready）
避免白屏（ready-to-show 与 show: false）
优雅地处理网络错误或路径问题（did-fail-load）
提升安全性（隔离远程内容、限制导航）

掌握这些之后，你就可以在任何复杂的桌面项目中自信地控制窗口内容了。下一节我们将深入探讨窗口间的通信机制，让多个渲染进程与主进程协同工作。