三个调试入口、IPC 合同测试与桌面排障

调试 Electron，先决定错误发生在哪里#

同一个按钮可能经过 Vue 事件、preload 函数、IPC、main 处理器和数据库。界面显示“保存失败”只说明结果没有完成，不能直接判断哪层有问题。熟悉浏览器 DevTools 是优势，但 Electron 需要增加主进程调试入口，并理解 preload 运行在独立上下文。本章目标是能够用证据把错误缩到一个边界，而不是靠重启、清缓存和放宽安全配置碰运气。

前置是能启动最小 Electron 窗口、了解 invoke/handle 与 Promise。下面一组实验在普通 Node 中验证合同，一组需要真实 Electron 桌面；练习再把日志写成可检查的数据。代码不包含真实密钥、数据库或远程服务，所以你可以先学清诊断结构，再接回业务项目。

renderer 的 DevTools 适合看 DOM、样式、网络、Vue 状态和页面脚本异常。main 在独立 Node 环境执行，它的 console 通常出现在启动应用的终端，不会自动出现在窗口 Console。preload 虽然为窗口运行，却位于隔离上下文；它的加载错误可以在主进程监听，也可以在对应窗口的 DevTools 中检查。三处都叫 console，不代表输出会流向同一个地方。

调试器能暂停程序，也会改变时间关系#

调试 main 使用 Electron 的 inspect 参数。安装本章固定版本 Electron 44.3.0 后，可在受控本机执行 electron --inspect=127.0.0.1:9229 .；启动后通过 Chrome 的检查目标界面连接本地端口。需要在入口执行前暂停时使用 inspect-brk。断点暂停 main 时，窗口、IPC 与计时也可能表现异常，因此不要把断点下的超时直接解释为生产性能。主进程调试

调试端口具有很高权限，只绑定回环地址，结束后关闭调试进程，不应把它作为用户安装版的默认启动方式。日志能保留历史，断点能看现场，两者互补。某些竞态在打断点后消失，说明暂停改变了先后顺序，此时更适合带时间与编号的事件记录，而不是不断增加断点。

source map 让编译后位置映射回源文件，不会修复错误，也不保证发布包中源文件路径可访问。main、preload 和 renderer 如果分别编译，就有三份映射需要正确配置。为了先排除构建变量，本章 main/preload 使用 .cjs，页面使用未编译脚本；等定位方法稳定后，再回到 Vue/Vite 构建产物检查映射。

实验一：把 IPC 合同从 Electron 对象中分离#

建立 contract-lab，保存下面两个文件，Node 22.22.0 执行 node contract-check.cjs。合同只做一个文本整理动作：输入必须恰好包含 text，长度一到一百二十个 UTF-16 码元，首尾空白被去掉后仍不可为空。返回固定 envelope，不把任意异常堆栈跨边界发给页面。

function createTextHandler({ authorize }) {
  return async function handle(event, input) {
    if (!authorize(event)) return { ok: false, error: { code: "FORBIDDEN" } };
    if (!input || typeof input !== "object" || Array.isArray(input) ||
        Object.keys(input).length !== 1 || typeof input.text !== "string" ||
        input.text.length > 120 || input.text.trim().length === 0) {
      return { ok: false, error: { code: "INVALID_INPUT" } };
    }
    return { ok: true, data: { text: input.text.trim(), contractVersion: 1 } };
  };
}
module.exports = { createTextHandler };

const assert = require("node:assert/strict");
const { createTextHandler } = require("./text-contract.cjs");
const trustedEvent = {};
const handle = createTextHandler({ authorize: event => event === trustedEvent });
(async () => {
  assert.deepEqual(await handle(trustedEvent, { text: " hello " }),
    { ok: true, data: { text: "hello", contractVersion: 1 } });
  for (const input of [null, [], {}, { text: "" }, { text: "  " },
    { text: 1 }, { text: "x".repeat(121) }, { text: "ok", admin: true }]) {
    assert.equal((await handle(trustedEvent, input)).error.code, "INVALID_INPUT");
  }
  assert.equal((await handle({}, { text: "ok" })).error.code, "FORBIDDEN");
  assert.equal((await handle({}, { text: "ok", trusted: true })).error.code, "FORBIDDEN");
  console.log("contract checks passed");
})().catch(error => { console.error(error); process.exitCode = 1; });

这份检查验证输入、返回和授权调用顺序，但 trustedEvent 是测试夹具，不是真实 WebFrameMain。它不能证明 renderer 无法伪造发送者，也不能证明 contextIsolation 生效。纯函数分离的价值是快速验证业务合同，不是把 Electron 对象替换成普通对象之后就宣布桌面安全测试完成。

先授权再解析业务输入，可以使不可信来源得到一致拒绝，而不是借错误差异探测内部合同。正式应用也可以为运维记录详细分类，但面向页面的错误保持有限。字数限制在这里明确使用 JavaScript length，不假装它等于人眼字符数；涉及费用或文件大小时应另按字节或模型 token 计算。

实验二：一个可以逐层观察的诊断窗口#

建立 desktop-diagnostics，把 text-contract.cjs 复制到同目录，再保存下面五个文件。执行 npm install，随后 npm start；本文没有实际安装或打开 GUI。页面只有输入框与按钮，减少 Vue 编译对第一轮定位的干扰。需要回到 Vue 时，事件路径仍然相同。

{
  "name": "desktop-diagnostics",
  "version": "1.0.0",
  "private": true,
  "main": "main.cjs",
  "scripts": { "start": "electron .", "debug:main": "electron --inspect=127.0.0.1:9229 ." },
  "devDependencies": { "electron": "44.3.0" }
}

const { app, BrowserWindow, ipcMain, session } = require("electron");
const path = require("node:path");
const { pathToFileURL } = require("node:url");
const { createTextHandler } = require("./text-contract.cjs");
let win;
const page = pathToFileURL(path.join(__dirname, "index.html")).href;
function log(event, details = {}) {
  console.log(JSON.stringify({ at: new Date().toISOString(), process: "main", event, ...details }));
}
app.whenReady().then(async () => {
  session.defaultSession.setPermissionRequestHandler((_wc, _permission, done) => done(false));
  session.defaultSession.setPermissionCheckHandler(() => false);
  win = new BrowserWindow({
    width: 800, height: 560,
    webPreferences: { preload: path.join(__dirname, "preload.cjs"),
      contextIsolation: true, sandbox: true, nodeIntegration: false }
  });
  const wc = win.webContents;
  wc.setWindowOpenHandler(() => ({ action: "deny" }));
  wc.on("will-navigate", event => event.preventDefault());
  wc.on("preload-error", (_event, _preloadPath, error) =>
    log("preload-error", { message: error.message }));
  wc.on("did-fail-load", (_event, code, description, _url, isMainFrame) =>
    log("did-fail-load", { code, description, isMainFrame }));
  wc.on("render-process-gone", (_event, details) =>
    log("render-process-gone", { reason: details.reason, exitCode: details.exitCode }));
  win.on("unresponsive", () => log("unresponsive"));
  win.on("responsive", () => log("responsive"));
  const handle = createTextHandler({
    authorize: event => event.sender === wc &&
      event.senderFrame === wc.mainFrame && event.senderFrame.url === page
  });
  ipcMain.handle("text:normalize", async (event, input) => {
    log("ipc-received"); // 不记录用户正文。
    const result = await handle(event, input);
    log("ipc-finished", { ok: result.ok });
    return result;
  });
  await win.loadFile(path.join(__dirname, "index.html"));
  wc.openDevTools({ mode: "detach" }); // 仅此教学诊断入口主动打开。
  log("window-loaded");
}).catch(error => { console.error(error); app.exit(1); });
app.on("window-all-closed", () => app.quit());

const { contextBridge, ipcRenderer } = require("electron");
console.log("preload: bridge installation");
contextBridge.exposeInMainWorld("textTool", {
  normalize: text => ipcRenderer.invoke("text:normalize", { text })
});

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="Content-Security-Policy"
    content="default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'">
  <title>IPC 诊断</title>
</head>
<body>
  <label>文本 <input id="text" value=" hello " maxlength="120"></label>
  <button id="run">整理</button>
  <p id="output" role="status">等待操作</p>
  <script src="./renderer.js"></script>
</body>
</html>

const output = document.querySelector("#output");
document.querySelector("#run").addEventListener("click", async () => {
  console.log("renderer: click");
  if (!window.textTool) {
    output.textContent = "preload 接口不存在";
    return;
  }
  try {
    const result = await window.textTool.normalize(document.querySelector("#text").value);
    output.textContent = result.ok ? result.data.text : result.error.code;
    console.log("renderer: result received", { ok: result.ok });
  } catch {
    output.textContent = "IPC 连接失败";
  }
});

正常点击后，页面显示 hello；renderer Console 出现 click 与 result received；main 终端出现 ipc-received、ipc-finished。它们形成跨边界的最小证据链。把 preload 文件名临时改错，应观察 preload-error 与接口不存在；恢复后再把页面脚本路径改错，主文档可能仍加载成功，但按钮没有 click 日志。两种白屏或无响应现象的发生位置不同。

实验使用固定本地页面，来源检查包含 webContents 与主 frame 身份，再比较页面 URL。生产路由可能带 hash 或查询参数，应按应用真正允许的导航规则规范化比较；不能为了让检查通过，退化成“只要字符串包含 index.html”。窗口重建后也要更新对应对象，避免拿旧窗口引用判定新请求。

用一条失败路径训练定位顺序#

假设用户点击保存没有反应。先看 renderer 是否记录 click；没有就查事件绑定、遮挡、disabled 与组件异常。如果有 click，却提示 bridge 不存在，查 preload 加载日志和路径；bridge 存在但 main 没收到请求，查频道名、invoke 参数与处理器是否注册。main 收到但没有完成，才继续查业务 Promise、I/O 和死锁。

若 main 已记录完成而 renderer 没显示，检查返回值结构、窗口是否已销毁以及组件是否已经卸载。特别是用户快速切换页面时，旧 Promise 完成可能写回新界面状态；这属于请求关联问题，不能用增加 IPC 超时掩盖。给请求分配操作编号，在日志与 UI 状态中保留对应关系，可以验证结果属于哪次点击。

白屏时先看 did-fail-load 的 isMainFrame。主文档失败可能来自路径、协议或入口选择；文档成功但某个脚本加载失败，应去 Network 与 Console 继续查资源。did-fail-load 并不是所有 JavaScript 异常的统一出口，不能只有这一个监听器。Vue 组件报错与 preload 加载失败也不共享同一个错误处理通道。

render-process-gone 表示渲染进程退出，详情可能区分正常退出、崩溃或被终止。不能遇到它就无限 reload：如果本地数据或脚本稳定触发崩溃，循环重载只会重复损失用户操作。应保存有限诊断信息，显示恢复选择，并限制自动恢复次数。unresponsive 也不等于已经崩溃，先观察主线程与渲染线程各自是否被长任务占用。

日志要能关联，但不要顺手变成数据副本#

一条有用的事件记录应包含时间、进程角色、事件名、操作编号和结果分类。时间帮助排序，但跨进程时钟与异步刷新可能让文本顺序不完全等于因果顺序；明确编号比单看控制台上下排列可靠。长期日志需要轮转与容量限制，启动应用时打印一条版本、平台和数据 schema，可以帮助确认用户运行的实际制品。

不要把 IPC 参数、文件全文和错误对象所有属性直接 JSON.stringify。堆栈里可能有用户目录，参数里可能有凭据，第三方错误可能包含完整请求。主进程保留受控技术细节，renderer 得到稳定错误码；用户导出诊断文件前，应能了解包含哪些数据。日志脱敏是白名单字段选择，不是最后用一个正则替换所有敏感内容。

测试也要区分证据层。Node 合同测试覆盖确定性输入与输出；真实 Electron 测试覆盖 preload 注入、IPC 序列化、发送者校验和窗口生命周期；安装版测试覆盖打包资源、权限、原生模块和平台行为。同一个测试名字写“桌面测试”没有意义，报告应该说明运行了哪个可执行文件、使用什么构建以及验证了哪些路径。

故障复现需要固定哪些条件#

一个可用复现不只是“点击这里会失败”。它还要包含应用版本、平台架构、启动方式、数据版本、输入内容的最小必要部分和出现频率。源码模式能复现还是只有打包模式能复现，是第一轮就该确定的信息。开发目录会提供很多额外文件和权限，依赖它们的错误通常只有离开该目录才出现。

如果问题偶发，先保存一条失败与一条成功的事件轨迹，比较它们在哪个阶段分叉。不要一边修改代码一边不断改变输入，否则无法知道修复来自哪一项变化。对于竞态，增加操作编号与顺序断言通常比延长超时更有价值；延长超时可能只是降低出现概率，并没有消除错误关联。

复现文件应尽量最小化，但不能删掉触发条件。某份文档只有表格或特殊编码时失败，缩减样本时要保留相关结构。用户数据不能直接公开放进仓库；可以构造等价无敏感内容的夹具，并说明它复现的是哪种结构。若只能在受控原数据上复现，报告就应诚实保留这个限制。

让一条 IPC 请求具有可检查的身份#

请求编号不是授权凭证，它只用于追踪。main 可以为接收到的操作分配编号，并将它带到业务日志与结果中；renderer 保存当前操作编号，避免把旧结果写进新表单。多窗口场景还需要记录窗口或会话归属。编号之间有映射即可，不必让所有层强行共用同一个字段名。

IPC 处理器未注册时，invoke 通常会以失败 Promise 暴露；处理器内部返回业务拒绝，则应是可识别的结果对象。这两种情况应分别测试。前者意味着应用装配或生命周期有问题，后者意味着请求不满足合同。把两者都包装成 ok:false 而不保留分类，会让你无法判断应该重试操作还是重新启动应用。

抛出的 Error 跨 IPC 后并不保证保留所有自定义属性、原型和完整堆栈。不要依赖 renderer 通过 instanceof 某个主进程自定义错误类来区分失败。稳定的错误码与允许字段组成数据合同，详细技术异常留在主进程日志中。这样即使以后将业务执行移到 utility process，错误表达仍然一致。

测试设计从反例开始更容易发现边界问题#

成功输入只能证明正确路径存在。来源不可信、空输入、额外字段、超长文本、处理器未注册与窗口销毁，才能检验应用是否在边界上保持正确行为。选择反例时围绕已声明合同，不必为每一行代码机械写对应断言。一个能证明旧实现错误的反例，比十个重复成功断言更有诊断价值。

例如测试发送者时，不应让 mock 从 payload.trusted 读取真假，然后得出权限正确的结论，因为真实页面同样能填写这个字段。实验使用注入的 authorize，只验证处理器确实在处理输入前调用它；真实 Electron 层还要验证 webContents 与 frame。测试替身替代了哪一层能力，应写在测试说明里。

测试超时时，先区分等待事件未发生、程序未退出、句柄未关闭与真实处理很慢。Node 程序打印 passed 后仍不退出，可能还有 Worker、文件监视器或定时器存活。桌面程序关闭窗口后进程仍在，也可能是平台预期生命周期，不能直接判泄漏。根据应用合同判断，然后检查具体资源拥有者。

主进程与渲染进程性能要分别观察#

页面动画卡顿，可能是 renderer 做了大量计算；整个应用菜单和窗口操作迟迟不响应，则要检查 main 是否阻塞。两个问题同时出现时，也可能是系统 CPU 或内存压力，而不是某一条 JavaScript 循环。先用最小任务观察哪一侧日志和计时停止，再选择对应性能工具。

DevTools Performance 可以分析 renderer 的脚本、布局和绘制，但不会替你展示所有主进程任务。main 可以通过 Node 检查器与性能记录观察长任务，后台执行器则需要自己的耗时与资源信息。把所有计时都放在点击前后，只能知道端到端慢，不能知道慢在计算、通信、等待还是绘制。

测量日志本身也有成本。每一行解析都同步打印，可能显著改变任务速度；海量 Console 对象还可能保留引用影响内存。性能测量时使用合适粒度的计数与阶段事件，并比较启用和关闭详细诊断的差异。不要把调试模式的耗时直接作为用户安装版承诺。

从问题修复走到可交付证据#

定位后先写清触发条件和错误机制，再做最小修改，然后用同一个复现验证结果。若修复 preload 路径，就重新验证真实 preload 注入；若修复纯输入合同，先跑离线合同检查；若涉及安装包资源，必须从新生成的应用目录启动。测试层级应该与改动落点一致，不能只选择最方便的一层。

修复后的报告应保留原失败证据、修改点和新结果，不必堆满终端日志。没有运行的平台或打包模式明确列为未验证，而不是写“理论支持”。这种范围说明不是推卸责任，它告诉后续维护者还有哪些工作需要实际环境，避免一个范围有限的检查在转述中被放大。

最后清理诊断专用的强制 DevTools、临时断点与敏感日志，但保留稳定错误分类和必要事件记录。调试工具帮助开发者进入现场，产品中的恢复信息帮助用户理解下一步，两者面对不同读者。正式界面不需要暴露整段堆栈，也不应该只显示毫无信息的“失败了”。

练习：构造不会泄露正文的诊断记录#

下面两个完整文件组成离线实验，执行 node diagnostic-check.cjs。要求只保留指定字段，缺少必要编号或非法阶段时拒绝；输入中即使附带 token、正文和路径，也不能进入结果。它不尝试识别全世界的敏感字段，而是根本不复制未允许字段。

function diagnostic(input) {
  if (!input || typeof input.operationId !== "string" ||
      !/^[a-z0-9-]{1,64}$/i.test(input.operationId) ||
      !["received", "validated", "completed", "failed"].includes(input.stage) ||
      !["main", "preload", "renderer"].includes(input.process)) {
    throw new Error("INVALID_DIAGNOSTIC");
  }
  const record = {
    operationId: input.operationId, process: input.process, stage: input.stage
  };
  if (input.code !== undefined) {
    if (!/^[A-Z_]{1,40}$/.test(input.code)) throw new Error("INVALID_ERROR_CODE");
    record.code = input.code;
  }
  return record;
}
module.exports = { diagnostic };

const assert = require("node:assert/strict");
const { diagnostic } = require("./diagnostic.cjs");
const record = diagnostic({
  operationId: "op-12", process: "main", stage: "failed", code: "WRITE_FAILED",
  token: "secret", text: "private body", path: "private-location"
});
assert.deepEqual(record, {
  operationId: "op-12", process: "main", stage: "failed", code: "WRITE_FAILED"
});
assert.equal(JSON.stringify(record).includes("secret"), false);
assert.throws(() => diagnostic({ operationId: "op-12", process: "main", stage: "unknown" }),
  /INVALID_DIAGNOSTIC/);
console.log("diagnostic checks passed");

把 record 写入文件时，还要处理文件权限、轮转和写失败；本练习只验证内容选择，不声称已经搭建日志系统。发生崩溃后，诊断日志与操作数据应独立管理，不能因为日志写不进去就让用户数据保存一起失败。对审计必达的操作则要另行定义事务与失败策略，不能用普通调试日志充当业务凭据。

验收时，先运行两个离线检查，再在真实桌面逐个制造 preload 路径错误、页面脚本错误、合同错误并恢复。最终报告注明哪些错误确实观察到、哪些只做了静态检查。本文编写期只验证 Node 程序，未执行真实窗口、调试器附加或进程崩溃实验。自测一：窗口 Console 能看到所有 main 日志吗？不能。自测二：mock 发送者检查通过等于真实来源安全吗？不等于。自测三：白屏一定是 Vue 报错吗？可能更早发生在文档或资源加载。

继续阅读 Electron 调试概览、webContents 事件 与 IPC 指南。查文档时先确认事件属于 BrowserWindow 还是 webContents，订阅在错误对象上通常不会报明显错误，只会让你永远收不到期望事件。

本章验证记录#

Node 22.22.0 已运行 contract-check.cjs 与 diagnostic-check.cjs，验证合同反例、授权调用边界和白名单日志字段。诊断窗口的 main.cjs、preload.cjs、renderer.js 仅做语法检查；没有实际附加检查器、打开 DevTools、制造渲染进程崩溃或完成真实 IPC 验收。