Electron NavigationHistory API 详解：主进程侧导航栈的查询、跳转、编辑与恢复

本文以 Electron 官方 API 文档 NavigationHistory 类文档 为主体，系统讲解该类的索引体系、全部实例方法（查询、导航、编辑、restore 恢复）的语义与边界行为，并结合 lib/browser/api/web-contents.ts、shell/browser/api/electron_api_web_contents.cc 等源码与 spec/api-web-contents-spec.ts 测试用例，说明每个方法在 Chromium NavigationController 之上的真实实现链路，帮助你在主进程中构建“后退/前进、跳转任意历史页、删除历史项、克隆/恢复导航栈”等完整的浏览历史管理能力。

1. NavigationHistory 是什么，从哪里获取

NavigationHistory 是一个**主进程（Main Process）**类，用于管理导航条目列表，表示应用内用户的浏览历史（参见 术语表 中 Main Process 的定义）。

它有一个关键的使用约束（来自 docs/api/navigation-history.md）：

该类不从 'electron' 模块导出。它只作为 Electron API 中其他方法的返回值存在。

从源码结构看，这个“其他方法”实际上体现为 WebContents 实例上的只读属性。在 lib/browser/api/web-contents.ts 中，_init() 通过 Object.defineProperty 挂载了 navigationHistory 属性：

// lib/browser/api/web-contents.ts#L534-L549（节选）
Object.defineProperty(this, 'navigationHistory', {
  value: {
    canGoBack: this._canGoBack.bind(this),
    canGoForward: this._canGoForward.bind(this),
    canGoToOffset: this._canGoToOffset.bind(this),
    clear: this._clearHistory.bind(this),
    goBack: this._goBack.bind(this),
    goForward: this._goForward.bind(this),
    goToIndex: this._goToIndex.bind(this),
    goToOffset: this._goToOffset.bind(this),
    getActiveIndex: this._getActiveIndex.bind(this),
    length: this._historyLength.bind(this),
    getEntryAtIndex: this._getNavigationEntryAtIndex.bind(this),
    removeEntryAtIndex: this._removeNavigationEntryAtIndex.bind(this),
    getAllEntries: this._getHistory.bind(this),
    restore: ({ index, entries }) => { /* 见第 6 节 */ },
    ...
  },
  writable: false,
  enumerable: true
});

可见：

• 每个方法都是把内部 _xxx 私有绑定（最终调用 C++ 侧 electron_api_web_contents.cc 中注册的方法）bind 到当前 WebContents 上，因此一个 navigationHistory 实例始终与一个特定的 WebContents 绑定；
• 属性 writable: false，你无法替换整个 history 对象，只能调用其方法。

使用入口因此是：

const { BrowserWindow } = require('electron');
const win = new BrowserWindow();
win.webContents.navigationHistory; // NavigationHistory 实例

维护这样一个有序的导航条目列表，使用户既能向后（back）也能向前（forward）无缝浏览历史。

2. 索引体系：index 与 offset 两个概念

原文档给出了两个必须分清的概念：

• index（绝对索引）：顺序编号，最早访问的页面在索引 0，最近访问的页面在索引 N；每个 NavigationEntry 对应一个具体访问过的页面。
• offset（相对偏移）：相对于当前条目的整数位置。例如 offset 为 1 表示在历史中向前移动一页，-1 表示后退一页。

这一区分贯穿整个 API 命名：goToIndex(index) / canGoToIndex 使用绝对索引，goToOffset(offset) / canGoToOffset(offset) 使用相对偏移，getActiveIndex() 返回当前页的绝对索引。

从源码可以印证两者的换算逻辑。在 shell/browser/api/electron_api_web_contents.cc 中：

void WebContents::GoToOffset(int offset) {
  if (CanGoToOffset(offset))
    web_contents()->GetController().GoToOffset(offset);
}

bool WebContents::CanGoToIndex(int index) const {
  return index >= 0 && index < GetHistoryLength();
}

void WebContents::GoToIndex(int index) {
  if (CanGoToIndex(index))
    web_contents()->GetController().GoToIndex(index);
}

int WebContents::GetActiveIndex() const {
  return web_contents()->GetController().GetCurrentEntryIndex();
}

两点实现事实值得注意：

1. 非法参数是静默 no-op，而不是抛错：goToIndex / goToOffset 会先用 CanGoToIndex / CanGoToOffset 校验，越界时什么都不做。测试用例 spec/api-web-contents-spec.ts 中直接调用 goToIndex(-1) 和 goToIndex(length()) 验证其不产生任何效果（expectNoEffect），而 goToIndex(activeIndex) 跳向当前页同样是安全空操作；
2. 所有导航操作最终都委托给 Chromium 的 web_contents()->GetController()（即 content::NavigationController），Electron 在其上加了校验与封装层。

3. 数据单元：NavigationEntry 结构

每个历史条目都是 NavigationEntry 对象，文档定义的字段为：

字段	类型	说明
url	string	页面 URL
title	string	页面标题
pageState	string (可选)	base64 编码的数据串，包含 Chromium 页面状态，如当前滚动位置或表单值。Chromium 在导航事件发生前以及定期提交该状态

pageState 是 restore() 能力的关键：它让恢复导航栈时不只是恢复 URL 序列，还能尽量还原每个页面自身的状态（HTML 表单值、滚动位置等）。

4. 查询方法：canGoBack / canGoForward / canGoToOffset / getActiveIndex / getEntryAtIndex / length / getAllEntries

4.1 布尔查询

• canGoBack()：返回 boolean，浏览器能否后退到上一个网页。
• canGoForward()：返回 boolean，浏览器能否前进到下一个网页。
• canGoToOffset(offset)：参数 offset 为 Integer；返回 boolean，能否从当前条目移动到指定的相对 offset。

典型 UI 用法是：在渲染进程更新“后退/前进”按钮的可用状态前，先在主进程轮询这两个布尔值。测试 spec/api-web-contents-spec.ts 验证了完整状态机：初始时 canGoBack() 为 false；导航后 getActiveIndex() 变为 1、canGoBack() 变为 true；调用 goBack() 后 getActiveIndex() 回到 0。

4.2 索引与条目

• getActiveIndex()：返回 Integer，当前页的索引——后退/前进/重载都以它为基准。
• getEntryAtIndex(index)：参数 index 为 Integer；返回 NavigationEntry。若 index 越界（大于历史长度或小于 0），返回 null。
• length()：返回 Integer，历史长度。
• getAllEntries()：返回 NavigationEntry[]，该 WebContents 的完整历史。它是配合 restore() 做跨 WebContents 迁移的数据来源。

getAllEntries() 有一个源码级的细节：在 electron_api_web_contents.cc 中，如果历史只含一条 InitialEntry（即还没有真正加载过任何页面），会直接返回空数组：

std::vector<content::NavigationEntry*> WebContents::GetHistory() const {
  const int history_length = GetHistoryLength();
  auto& controller = web_contents()->GetController();

  // If the history is empty, it contains only one entry and that is
  // "InitialEntry"
  if (history_length == 1 && controller.GetEntryAtIndex(0)->IsInitialEntry())
    return {};
  ...
}

也就是说：对未导航过的新窗口调用 getAllEntries() 会得到 []，而不是含一个空白条目的数组——这正好与 restore() 要求目标 WebContents 处于初始状态形成配合。

5. 导航方法：goBack / goForward / goToIndex / goToOffset

• goBack()：后退一个网页。
• goForward()：前进一个网页。
• goToIndex(index)：导航到指定的绝对索引。
• goToOffset(offset)：导航到相对当前条目的指定偏移位置。

四者均为同步调用、无返回值，导航本身是异步完成的。从源码结构看（electron_api_web_contents.cc，见第 2 节代码），每个方法都先做 CanGoTo* 校验，非法调用直接忽略，不会触发任何导航事件。

测试 spec/api-web-contents-spec.ts 给出了一组可复现的行为基线：

// 3 个历史条目、当前 activeIndex === 2 时：
w.webContents.navigationHistory.canGoToOffset(-1)  // false（只有 2 个可后退位置之一，-1 合法但断言了边界）
w.webContents.navigationHistory.canGoToOffset(-2) // true
w.webContents.navigationHistory.goToOffset(-2);   // activeIndex 变为 0
// 回到 activeIndex === 1 后：
w.webContents.navigationHistory.canGoToOffset(1)  // true
w.webContents.navigationHistory.goToOffset(1);    // activeIndex 变为 2

6. 编辑历史：clear() 与 removeEntryAtIndex(index)

• clear()：清空导航历史。实现上（electron_api_web_contents.cc）调用 NavigationController::PruneAllButLastCommitted()，即裁剪到“只保留最后一次已提交条目”，并带有 CanPruneAllButLastCommitted() 保护——在“没有真实历史”的罕见状态下不会执行裁剪。
• removeEntryAtIndex(index)：参数 index 为 Integer；删除指定索引的导航条目。不能删除当前处于“活动索引”位置的条目。返回 boolean，表示该条目是否确实从 webContents 历史中被移除。

从源码结构看，RemoveNavigationEntryAtIndex 先复用 CanGoToIndex 做范围校验（越界返回 false），再委托 controller.RemoveEntryAtIndex(index)（electron_api_web_contents.cc）。测试用例 spec/api-web-contents-spec.ts 覆盖了四种情形：

const wasRemoved = w.webContents.navigationHistory.removeEntryAtIndex(1); // 删除第二条，成功，length() 减 1
const wasRemoved = w.webContents.navigationHistory.removeEntryAtIndex(activeIndex); // 删除活动索引 -> false
const wasRemoved = w.webContents.navigationHistory.removeEntryAtIndex(5);  // 越界（大于长度）-> false
const wasRemoved = w.webContents.navigationHistory.removeEntryAtIndex(-1); // 负索引 -> false

这一 API 适合做“历史去重/黑名单过滤”类功能：例如在 did-finish-load 后检查并删除不应进入历史的中间页条目（注意不能删当前页）。

7. 进阶能力：restore(options) 跨 WebContents 恢复导航栈

restore(options) 是此类中最有实战价值的 API。文档原文的要点是：

恢复导航历史，并加载栈中给定的条目。它会尽力恢复的不仅是导航栈，还有各个页面自身的状态——例如 HTML 表单值、滚动位置等。建议在创建任何导航条目之前调用，理想情况是在对 webContents 调用 loadURL() 或 loadFile() 之前。该 API 允许你创建恢复、重建或克隆其他 webContents 的常见流程。

参数与返回值（完整继承自 docs/api/navigation-history.md）：

• options Object
  • entries NavigationEntry[] — 之前某次 getAllEntries() 调用的结果
  • index Integer (可选) — 应加载的栈索引。设为 0 时 webContents 加载第一个（最旧）条目；留空（undefined）时 Electron 自动加载最后一个（最新）条目

Returns Promise<void> — 当所选导航条目完成加载（对应 did-finish-load 事件）时 resolve；页面加载失败（对应 did-fail-load 事件）时 reject。已内置一个 noop 拒绝处理，因此不会触发 unhandled rejection 错误。

7.1 JS 包装层：index 默认值与错误处理

lib/browser/api/web-contents.ts 中 restore 的包装逻辑值得逐行读：

restore: ({ index, entries }: { index?: number; entries: NavigationEntry[] }) => {
  if (index === undefined) {
    index = entries.length - 1;   // 默认加载“最新”条目
  }

  if (index < 0 || !entries[index]) {
    throw new Error(
      'Invalid index. Index must be a positive integer and within the bounds of the entries length.'
    );
  }

  const p = _awaitNextLoad.call(this, entries[index].url);
  p.catch(() => {});              // noop 拒绝处理，避免 unhandled rejection

  try {
    this._restoreHistory(index, entries);
  } catch (error) {
    return Promise.reject(error);
  }

  return p;
}

注意两个行为边界：

1. index 是 undefined 时默认加载最新条目；若传入的是显式非法值（负数或越界），在 JS 层同步抛出 Error，而不是返回 rejected Promise；
2. _awaitNextLoad 返回的 Promise 先挂 catch(() => {}) 防止未处理拒绝，原 Promise 再返回给调用方，因此你的 await 仍然能收到加载失败的 rejection。

7.2 C++ 层：只允许在“未加载过页面”的 WebContents 上恢复

C++ 侧 RestoreHistory（electron_api_web_contents.cc）有三个硬性约束：

1. 目标必须处于初始条目状态：如果 GetLastCommittedEntry()->IsInitialEntry() 不成立（即该 webContents 已经加载过页面），直接抛出 "Cannot restore history on webContents that have previously loaded a page."。这正是文档建议“在 loadURL()/loadFile() 之前调用”的底层原因；
2. 逐条校验 entries：任何一条无法从 V8 值转换为有效的 content::NavigationEntry，就抛出 "Failed to restore navigation history: Invalid navigation entry at index N."；
3. UserAgent 一致性：恢复前会读取当前 webContents 的 UA 覆盖设置，给每条新条目打上 SetIsOverridingUserAgent 标记并在恢复时重新 SetUserAgentOverride，保证克隆出的历史在 UA 行为上与原栈一致。

核心恢复调用为：

web_contents()->GetController().Restore(
    index, content::RestoreType::kRestored, &navigation_entries);
web_contents()->GetController().LoadIfNecessary();

即把整条新历史栈一次性装入 NavigationController，加载到指定 index 位置的条目。

7.3 典型场景：克隆窗口时迁移完整浏览历史

// 从已浏览多个页面的 sourceWindow 克隆出带完整历史的 newWindow
const { BrowserWindow } = require('electron');

const entries = sourceWindow.webContents.navigationHistory.getAllEntries();
const activeIndex = sourceWindow.webContents.navigationHistory.getActiveIndex();

const newWindow = new BrowserWindow();
// 关键：必须在 newWindow 加载任何页面之前调用 restore
newWindow.webContents
  .navigationHistory.restore({ entries, index: activeIndex })
  .then(() => {
    console.log('历史栈已恢复并加载到第', activeIndex, '条');
  })
  .catch((err) => {
    console.error('恢复失败（did-fail-load）:', err);
  });

配合第 6 节提到的 pageState 机制，新窗口的对应页面会尽力还原滚动位置与表单值。

8. 从 WebContents 直接调用的方法已废弃

如果你在旧代码里见到 webContents.goBack()、webContents.canGoBack() 等直接方法，它们已被迁移到 navigationHistory 命名空间下。lib/browser/api/web-contents.ts 中通过 deprecate.warnOnce 逐一登记了映射，例如：

const goBackDeprecated = deprecate.warnOnce('webContents.goBack', 'webContents.navigationHistory.goBack');
WebContents.prototype.goBack = function () {
  goBackDeprecated();
  return this._goBack();
};

完整映射关系：

已废弃（仍可用，触发一次性警告）	替代 API
webContents.canGoBack()	webContents.navigationHistory.canGoBack()
webContents.canGoForward()	webContents.navigationHistory.canGoForward()
webContents.canGoToOffset(offset)	webContents.navigationHistory.canGoToOffset(offset)
webContents.clearHistory()	webContents.navigationHistory.clear()
webContents.goBack()	webContents.navigationHistory.goBack()
webContents.goForward()	webContents.navigationHistory.goForward()
webContents.goToIndex(index)	webContents.navigationHistory.goToIndex(index)
webContents.goToOffset(offset)	webContents.navigationHistory.goToOffset(offset)

值得注意的是，getActiveIndex、length、getEntryAtIndex、removeEntryAtIndex、getAllEntries、restore 这些条目级 API 只存在于 navigationHistory 上，WebContents 原型从未直接暴露对应方法——这正是 NavigationHistory 类独立成类的原因。

另外，<webview> 标签侧也复用这套语义：lib/common/web-view-methods.ts 定义了 navigationHistorySyncMethods 同步方法集合（并在第 60 行附近与其他同步方法合并导出），由 lib/browser/guest-view-manager.ts 用于在 guest 视图上代理同名操作，因此 webview 与原生窗口遵循相同的“index 绝对 / offset 相对”模型。

9. 行为速查与验证清单

综合文档语义、源码实现与 spec/api-web-contents-spec.ts 的测试描述，可得到如下速查表：

操作	非法/边界输入行为
canGoBack() / canGoForward() / canGoToOffset(offset)	永不出错，返回 boolean
goToIndex(index) / goToOffset(offset)	越界静默 no-op（先 CanGoTo* 校验，见源码）
getEntryAtIndex(index)	越界返回 null
removeEntryAtIndex(index)	越界返回 false；删除活动索引条目失败返回 false
restore({entries, index})	index 显式非法：JS 层同步抛错；目标 webContents 已加载过页面：C++ 层抛错；加载失败：Promise reject（已挂 noop catch，不会 unhandled rejection）
clear()	无可裁剪历史时安全跳过（CanPruneAllButLastCommitted 保护）

10. 小结

NavigationHistory 是 Electron 把 Chromium NavigationController 的能力以“主进程可编程”的方式暴露出来的完整封装：以 index/offset 双坐标系定位历史，用一组查询 + 导航 + 编辑方法覆盖日常的浏览器式操作，再用 getAllEntries() 与 restore() 组成“导出—装载”闭环，支撑窗口克隆、会话恢复等高级流程。开发时的三条纪律：

1. 只在主进程、通过 webContents.navigationHistory 访问；
2. 所有 goToIndex/goToOffset 调用前先用 canGoTo* 或范围判断兜底，因为越界调用是静默忽略的；
3. restore() 必须在目标 WebContents 加载过任何页面前调用，并传入之前 getAllEntries() 的原始结果（含 pageState 才能还原页面状态）。

主要参考路径：docs/api/navigation-history.md、docs/api/structures/navigation-entry.md、lib/browser/api/web-contents.ts、shell/browser/api/electron_api_web_contents.cc、lib/common/web-view-methods.ts、spec/api-web-contents-spec.ts。