Electron 桌面端出问题时，我会先打一个诊断证据包

桌面端问题最容易卡在一句话里：用户说刚才点了没有反应。Web 端还能靠服务器日志、浏览器控制台和请求链路去拼现场，Electron 项目多了一层主进程和 preload，问题经常横跨窗口生命周期、本地文件、系统权限、网络请求和前端状态。最近我在整理一个 AI 工具桌面壳时，先补了一套诊断证据包，把一次异常的关键材料打在一起，再让排障从猜测回到证据。

Electron 主进程、preload、renderer、netLog 汇入诊断证据包的流程图

原创示意图：主进程日志、preload 安全桥、渲染进程事件和 netLog 网络记录汇入同一个诊断证据包。来源：Codex image generation

问题背景

Electron 官方的进程模型文档说明，应用由 main 和 renderer 两类主要进程组成，main 负责入口、窗口和生命周期，renderer 负责页面内容。这个结构很适合把 Web 能力包装成桌面体验，但也带来一个现实问题：前端报错只说明页面发生了什么，主进程日志才知道窗口、菜单、文件和系统调用发生了什么，网络层还可能藏在 Chromium session 里。

我之前的做法是让用户截图，开发侧再去翻零散日志。效率很低，因为截图没有时间线，日志没有用户动作，网络失败又缺少上下文。后来我改成在应用里放一个“生成诊断包”的入口，用户触发后收集最近几分钟的材料，脱敏后压缩成一个文件。

关键难点

第一个难点是边界。renderer 不能随便拿本地路径和 Node 能力，Electron 的 contextBridge 文档也提醒，暴露给页面的 API 要谨慎，完整透传 ipcRenderer 会放大风险。所以诊断入口只暴露一个很窄的方法，例如 window.desktopDiagnostics.createBundle()，它只接受问题描述和可选时间范围。

第二个难点是时间线。主进程写日志、renderer 记录用户动作、netLog 记录网络事件，它们必须共享同一个 traceId。没有 traceId 时，三份材料都存在，仍然很难解释一次失败的先后顺序。

第三个难点是敏感信息。Electron 的 netLog 文档里，captureMode 可以选择 default、includeSensitive 或 everything。日常诊断我只用 default，再对请求头、文件路径、账号标识做二次清理。需要更高采样级别时，必须让用户知道会包含更细的网络信息。

解决思路

我的实现是把证据包当成一个产品内的只读导出流程。renderer 只负责发起请求和补充用户动作摘要，preload 只做安全桥，main process 负责创建目录、聚合日志、停止网络记录和打包。Electron 的 IPC 教程给了典型的双向调用模式，ipcRenderer.invoke 和 ipcMain.handle 配合使用，很适合这种需要返回结果的桌面能力。

日志目录不直接写在应用安装目录里。Electron 的 app API 提供 app.setAppLogsPath() 和 app.getPath("logs")，可以把应用日志放到平台约定的位置。我的规则是启动时确定 logs 目录，诊断包再创建一个带时间戳和 traceId 的子目录，避免覆盖历史材料。

ipcMain.handle("diagnostics:create", async (_event, input) => {
  const traceId = createTraceId();
  const dir = await createDiagnosticsDir(app.getPath("logs"), traceId);
  const netPath = path.join(dir, "netlog.json");

  await netLog.startLogging(netPath, { captureMode: "default" });
  await writeRendererEvents(dir, input.recentEvents, traceId);
  await writeMainSnapshot(dir, traceId);
  const writtenNetPath = await netLog.stopLogging();

  return zipAndRedact({ dir, traceId, writtenNetPath });
});

关键步骤

落地时我只保留四类文件。第一类是 main.log，记录窗口创建、路由跳转、托盘动作、文件读写和更新检查。第二类是 renderer-events.jsonl，只收按钮点击、关键状态变化和前端异常摘要，不收完整页面数据。第三类是 netlog.json，由 netLog 生成，默认只保留请求元数据。第四类是 environment.json，记录应用版本、系统平台、构建渠道和关键 feature flag。

打包前还会做一次脱敏扫描。路径只保留尾部几级，邮箱和 token 用固定占位符替换，过大的日志会裁剪到最近窗口。最后生成一个 manifest.json，写清楚每个文件的来源、时间范围、traceId 和脱敏规则。这样同事拿到压缩包后，先读 manifest，再按时间线看日志，不需要先问用户十个问题。