前端 SPA 导航怎么统一接管：Navigation API 的拦截、失败恢复与回退

SPA 页面最容易漏掉的，不是一次普通的链接点击，而是同一套页面里发生的各类导航行为：用户点链接、按浏览器后退、提交表单、脚本跳转、刷新当前入口。只监听点击事件，再手动调用 history.pushState()，通常只能覆盖其中一部分，结果就是加载状态、滚动位置和错误提示各走各的分支。

Navigation API 提供了一个统一的 window.navigation 入口。它能捕获导航、在提交前接管加载流程，并通过 navigatesuccess 和 navigateerror 收拢结果。下面用一个文章列表 SPA 的“路由加载器”说明最小接入方式，以及浏览器不支持时如何平稳回退。

先把 SPA 导航的触发面收齐

一个典型列表页至少有四条入口：点击站内链接、调用 navigation.navigate()、浏览器前进后退，以及表单或重定向触发的页面变化。Navigation API 的 navigate 事件会在这些导航开始时统一触发，事件对象还带有目标 URL、导航类型和是否包含 POST 数据等信息。

它的边界也要记清楚：Navigation API 主要面向同源的 SPA 页面，当前窗口里的导航历史才会被它管理；跨源跳转、下载和部分带表单数据的导航，不应该强行套上局部刷新的逻辑。

最小接入：只拦截可以由页面接管的导航

先保留服务端路由和普通链接，让增强逻辑只处理同源 HTML 页面。canIntercept 是一个实用的保护条件；遇到下载、跨源地址或带有不适合局部加载的数据时，直接让浏览器执行默认导航。

const app = document.querySelector('#app');
const busy = document.querySelector('#route-status');

if ('navigation' in window) {
  navigation.addEventListener('navigate', (event) => {
    const target = new URL(event.destination.url);
    const sameOrigin = target.origin === location.origin;

    if (!event.canIntercept || !sameOrigin || event.downloadRequest) {
      return;
    }

    event.intercept({
      scroll: 'manual',
      focusReset: 'after-transition',
      handler: () => loadRoute(target)
    });
  });
}

async function loadRoute(target) {
  busy.textContent = '正在加载';
  const response = await fetch(target.pathname + target.search, {
    headers: { Accept: 'text/html;fragment=1' }
  });
  if (!response.ok) throw new Error(`route-${response.status}`);
  app.innerHTML = await response.text();
  document.title = app.querySelector('[data-page-title]')?.dataset.pageTitle
    ?? document.title;
  busy.textContent = '已完成';
}

这里的关键不是把所有跳转都变成 Ajax，而是把“是否可以接管”放在一个入口判断。intercept() 的处理函数返回 Promise，浏览器会等待它完成；处理函数成功时触发导航成功事件，抛错或 Promise 拒绝时进入错误事件。

把加载、成功和失败变成明确门禁

加载器至少要有三个可检查的门禁：请求是否返回成功状态、返回内容是否包含页面根节点、提交后地址是否仍然是预期的同源地址。只检查 HTTP 200 不够，服务端返回登录页或错误模板时，页面仍可能被误替换。

navigation.addEventListener('navigatesuccess', (event) => {
  busy.dataset.state = 'ready';
  busy.textContent = `已打开 ${new URL(event.destination.url).pathname}`;
  document.querySelector('[autofocus], h1, main')?.focus?.();
});

navigation.addEventListener('navigateerror', (event) => {
  busy.dataset.state = 'error';
  busy.textContent = '页面加载失败，可重试';
  console.warn('route-failed', event.destination.url, event.error);
});

不要在错误事件里清空旧页面。旧内容还在时，用户至少知道自己刚才停在哪里；把错误提示和“重试”按钮放在状态栏里，比突然出现空白页更容易恢复。

失败恢复和后退操作怎么处理

路由加载前先记录当前滚动位置，只在成功后更新页面状态。加载失败时，不要修改业务数据，也不要再次创建一条历史记录；重试应复用目标 URL，并继续经过同一套拦截和门禁。

let lastScroll = { x: 0, y: 0 };

async function loadRoute(target) {
  lastScroll = { x: scrollX, y: scrollY };
  busy.dataset.state = 'loading';

  try {
    const response = await fetch(target.pathname + target.search);
    if (!response.ok) throw new Error(`route-${response.status}`);
    const html = await response.text();
    if (!html.includes('data-page-title')) throw new Error('invalid-fragment');
    app.innerHTML = html;
    scrollTo(0, 0);
  } catch (error) {
    scrollTo(lastScroll.x, lastScroll.y);
    busy.dataset.state = 'error';
    throw error;
  }
}

document.querySelector('#retry-route')?.addEventListener('click', () => {
  navigation.navigate(location.href).finished.catch(() => {});
});

多锁场景也要谨慎：如果加载器同时等待两个彼此依赖的异步资源，失败恢复可能卡成永远加载中的状态。把页面请求、模板校验和 DOM 替换保持在一条顺序链上，并给网络请求设置超时，是更容易排查的做法。

不支持 Navigation API 时的回退

能力检测不能只判断浏览器名称。没有 window.navigation 时，保留普通 href 链接即可由服务端完整渲染；如果产品必须保留局部切换，再单独挂载有限的 click 与 popstate 兼容层，但不要让这套旧逻辑和新事件同时改写页面。

function bootRouter() {
  if ('navigation' in window) {
    installNavigationRouter();
    return 'navigation-api';
  }

  document.querySelectorAll('a[data-spa]').forEach((link) => {
    link.removeAttribute('data-spa');
  });
  return 'server-rendered';
}

MDN 将 Navigation API 标为 2026 年起在最新设备和浏览器中逐步可用，同时提醒旧设备可能不支持。生产发布时建议把“增强路由”和“服务端可直达”当成两条都能验收的路径，而不是把兼容性押在一个全局开关上。

上线前的四个检查点

• 点击站内链接、脚本跳转、后退和前进，是否都能进入同一条加载路径。
• 跨源地址、下载链接和不适合局部渲染的表单，是否仍由浏览器默认处理。
• 接口 404、超时、返回错误模板时，旧页面是否保留，错误提示是否可见且可重试。
• 关闭 Navigation API 后，服务端直达、刷新和返回按钮是否仍能完成同一业务任务。

常见问题

Navigation API 能完全替代 History API 吗？

它是面向 SPA 导航的新统一入口，但仍要按浏览器兼容情况准备服务端或旧 API 回退。不要因为新 API 存在就删除可直达的服务端路由。

为什么拦截了 navigate，页面还是整页刷新？

常见原因是 canIntercept 为假、目标跨源、链接是下载，或者没有在事件里调用 intercept()。先记录事件目标和这些条件，再判断是不是框架路由配置问题。

失败时应该调用 navigation.navigate() 重新加载吗？

可以把重试作为一次新的导航，但重试按钮要防止重复点击，并继续经过同源判断、超时和响应内容校验。不要在错误回调里无条件递归重试。

结语

Navigation API 的价值在于把分散的导航入口收进一个事件模型，再把加载、成功、失败和回退变成能测试的状态。对于已有 SPA，最稳妥的落地顺序是先保留服务端可直达，再接入同源 HTML 导航，最后补齐错误恢复、滚动和焦点检查。