路由缓存

这一页解释 apps/admin 当前的页面缓存机制。它解决的是后台常见场景：用户在一个表单页、编辑页或查询页输入了一些内容，切到其他页面后再回来，页面组件不应该重新挂载，表单 state 和 DOM 草稿也不应该丢失。

当前实现不是简单在 <Outlet /> 外面包一层通用缓存组件，而是在 @skyroc/web-admin-layouts 的内容区维护 TanStack Router 的路由状态快照。这样切换路由时，已标记缓存的页面会被隐藏，但组件实例、React state 和 DOM 状态会继续留在页面树里。

适用场景

当前实现位置

开启缓存

静态路由直接在 staticData 上声明：

export const Route = createFileRoute('/(admin)/keep-alive-form')({
  component: KeepAliveFormVerify,
  staticData: {
    title: 'keep_alive_form',
    i18nKey: 'route.keep-alive-form',
    keepAlive: true,
    menu: {
      icon: 'mdi:form-select',
      order: 23
    }
  }
});

动态菜单模式下，后端 route 的 handle.keepAlive 会被应用侧适配：

const handle = route.handle ?? route.meta ?? {};

return {
  keepAlive: handle.keepAlive ?? undefined,
  path,
  title: handle.title ?? route.name ?? undefined
};

这两种入口最后都会进入 Menu.QuickReferenceMenu.keepAlive，再进入 tab 状态。页面缓存不是单独扫描 route tree，而是跟着“当前路由是否已经进入 tabs”这条链路走。

缓存链路

完整链路如下：

route staticData.keepAlive
  或 dynamic route handle.keepAlive
  -> menu-generator quickReferenceMenus[path].keepAlive
  -> getTabByMenuInfo(...).keepAlive
  -> useAdminTab().tabs
  -> AdminContent getKeepAliveKeys(...)
  -> CachedRoutePane

AdminContent 会为每个需要缓存的页面维护一个缓存项：

渲染时，每个缓存项都会创建一个独立的 CachedRoutePane。激活的 pane 显示出来，非激活的 pane 使用 display: none 隐藏。

缓存 key 怎么确定

缓存 key 复用 tabs 的 id 规则：

getTabIdByRoute(route.originPath, route.staticData?.tab?.multi ?? false, route.fullPath);

如果一个页面既需要缓存，又需要按照查询参数区分实例，就同时配置：

staticData: {
  keepAlive: true,
  tab: {
    multi: true
  }
}

不要把 keepAlive 当作浏览器级缓存。它只决定 React 页面实例是否保留；接口数据仍然由 React Query、业务状态或组件自己的请求逻辑控制。

为什么不是直接用 React Activity

React 19.2 的 <Activity> 可以隐藏并恢复子树的 UI 和内部状态。官方文档说明，隐藏时 React 会用 display: none 视觉隐藏子节点，并清理隐藏子树的 Effects；重新显示时再恢复之前的 state 并重新创建 Effects。

这和后台页面缓存的目标接近，但当前项目不能直接把它当作完整方案：

所以当前采用的是 TanStack Router 感知的缓存：隐藏页面时，同时保留该页面激活时的 router state 快照。这样 cached pane 里的 Outlet 仍然按照旧 match 树渲染，而不是被当前 URL 覆盖。

以后如果项目升级到 React 19.2 或更高，可以考虑把隐藏层从普通 div style={{ display: 'none' }} 换成 Activity mode="hidden"，但仍然需要保留“路由 state 快照”这一层，否则路由上下文问题不会消失。

生命周期行为

当前缓存实现的行为如下：

因为当前实现不会像 Activity 一样清理隐藏页 Effects，所以给页面开启缓存前要确认页面是否有这些副作用：

验证页面

当前仓库提供了一个验证页面：

/keep-alive-form

页面文件是：

apps/admin/src/pages/(admin)/keep-alive-form.tsx

它同时覆盖三类状态：

手动验证步骤：

1. 打开 /keep-alive-form。
2. 填写“项目名称”“处理人”“原生草稿”，点击“加一”。
3. 点击“切到关于”进入 /about。
4. 点击 tab 或菜单里的“缓存表单”返回。
5. 检查输入值、textarea 草稿、计数器和“实例 ID”是否保持不变。

如果实例 ID 改变，说明组件重新挂载了；如果只有 textarea 丢失，说明 DOM 没有被保留；如果只有 Form 值丢失，说明页面实例可能保留了，但表单被重建或主动 reset。

排查顺序

常见误区

相关位置