Nuxt 内置路由出口组件 `<NuxtPage>` 完全指南：Props、页面过渡与 Suspense 生命周期

<NuxtPage> 是 Nuxt 框架内置的路由出口组件，用于渲染位于 app/pages/ 目录下的顶层或嵌套页面，是文件路由系统的核心渲染节点。本文基于当前仓库（Nuxt 全栈 Vue 框架）的官方 API 文档与 packages/nuxt/src/pages/runtime/page.ts 源码实现，系统讲解它的内部结构、全部 Props、页面过渡与 keep-alive 配置方式、Suspense 下的生命周期差异、页面实例引用获取以及自定义 Props 透传技巧，读完即可在应用布局中正确地配置与调优路由页面渲染。

为什么应该使用 <NuxtPage> 而不是 <RouterView>

在 Nuxt 应用中，<NuxtPage> 与 Vue Router 的 <RouterView> 组件职责相似——它们都是路由组件的"出口"，决定当前匹配的路由组件渲染在哪里。但官方文档明确建议：必须使用 <NuxtPage> 而不是直接使用 <RouterView>。

<NuxtPage> 本质上是 <RouterView> 的一层封装，它的额外价值在于：

• 负责维护 Nuxt 内部的页面状态（例如页面级 route 的响应式派生、page:start / page:finish 等生命周期 Hook 的触发）；
• 如果绕过它直接使用 <RouterView>，内部状态得不到正确处理，可能导致 useRoute() 返回错误的路径；
• Nuxt 会自动扫描并渲染 app/pages/ 目录下的所有 Vue 组件，因此在使用 <NuxtPage> 时无需手动传入 name 与 route，它会由框架自动解析（见页面目录文档）。

源码中的组件定义印证了这一点：在 page.ts 中，组件通过 h(RouterView, { name: props.name, route: props.route, ...attrs }, ...) 将用户传入的 name 与 route 原样交给 <RouterView>，并通过自定义的插槽渲染逻辑接管了页面组件的挂载方式。这也解释了它为什么在 Props 类型上继承了 RouterViewProps。

<NuxtPage> 的内部控制结构

从实现视角看，<NuxtPage> 在客户端渲染的组件树大致等效于下面这段模板（仅示意，实际经组合式 API 与 VNode 构建）：

<template>
  <RouterView v-slot="{ Component }">
    <!-- 可选：启用页面切换过渡时 -->
    <Transition>
      <!-- 可选：启用页面状态保持时 -->
      <KeepAlive>
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </KeepAlive>
    </Transition>
  </RouterView>
</template>

这一嵌套层级对应了源码中的真实包装顺序：在 page.ts 中可以看到，最终渲染的 vnode 由 _wrapInTransition(...) 包裹 wrapInKeepAlive(...) 包裹 <Suspense> 组成，而 <Suspense> 内部再渲染 RouteProvider 来提供页面级的响应式 route。

三个要点：

1. 默认不启用 <Transition> 与 <KeepAlive>。在 schema 的 app 配置 中，app.pageTransition 与 app.keepalive 的默认值都是 false。
2. 需要在三个层级中启用它们：nuxt.config 全局配置、<NuxtPage> 组件上的 transition / keepalive Props、页面组件内通过 definePageMeta 按页配置。
3. 在页面组件中启用 <Transition> 时，必须保证页面模板只有一个根元素，否则过渡动画无法正确执行。

启用 Transition 与 KeepAlive 的三种方式

方式一：全局配置（nuxt.config）

export default defineNuxtConfig({
  app: {
    pageTransition: { name: 'page', mode: 'out-in' },
    keepalive: true,
  },
})

app.pageTransition 默认值为 false，app.keepalive 同样默认关闭（见 packages/schema/src/config/app.ts）。

方式二：在 <NuxtPage> 组件上按使用位置配置

<template>
  <NuxtPage transition="page" keepalive />
</template>

方式三：在页面组件内用 definePageMeta 单独定义

<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,
  transition: { name: 'page', mode: 'out-in' },
  keepalive: true,
})
</script>

从源码看，这些来源之间存在明确的优先级链。以 transition 为例，在 page.ts 中：

const hasTransition = !!(props.transition ?? routeProps.route.meta.pageTransition ?? defaultPageTransition)

即 <NuxtPage> 的 transition Prop > 路由记录的 meta.pageTransition（来自 definePageMeta）> 全局默认 app.pageTransition。随后这些配置通过 _mergeTransitionProps 合并（定义于 packages/nuxt/src/app/components/utils.ts），并在 onAfterLeave 回调里触发 page:transition:finish Hook。

keepalive 的解析逻辑类似（见源码第 184 行）：

const routeKeepaliveConfig = props.keepalive ?? routeProps.route.meta.keepalive ?? defaultKeepaliveConfig

另外源码中还处理了一个重要细节：如果某些页面通过 definePageMeta 开启了 keep-alive，当导航到未开启 keep-alive 的页面时，Nuxt 会把已开启页面组件的名称累积到 keepAliveInclude 集合中，并注入到有效的 <KeepAlive> 配置的 include 列表中，从而保证切换路由时已缓存页面不被清空（对应 issue #33610 的修复）。这一逻辑就实现在 page.ts 的 shouldAugmentInclude 分支中。

Suspense 下的页面生命周期差异

<NuxtPage> 在底层使用 <Suspense> 包装页面，因此页面切换时组件的生命周期行为与典型 Vue 应用不同：

• 在典型 Vue 应用中，新页面组件会在旧页面完全卸载之后才被挂载；
• 在 Nuxt 中，由于 Vue <Suspense> 的实现机制，新页面组件会在旧页面卸载之前就被挂载。

这一差异主要影响同时观察"旧页面卸载"与"新页面挂载"两个生命周期的代码（例如在 onUnmounted / onMounted 中执行清理与初始化逻辑的场景），编写跨页面共享状态或动画时需留意时序。

源码对该机制做了额外加固：快速连续导航时，组件会通过递增 suspenseKey 重新挂载 Suspense 边界（仅在已成功 resolve 过一次之后），避免未 resolve 的 Suspense 被提前拆除导致父级组件挂起（对应 issue #28425 / #34683）。同时，客户端在初次 hydration 期间如果组件在 Suspense resolve 前被卸载（例如布局切换），会通过 onBeforeUnmount 中的 done() 确保 hydration 流程正常收尾。

此外，客户端渲染分支还做了"陈旧 vnode 复用"处理：当导航导致某个 <NuxtPage> 暂时没有匹配的子页面组件时，会优先渲染旧的 vnode 直到新路由解析完成；对于已经卸载的 Suspense 边界上遗留的陈旧 vnode，则通过 isStaleVNode 判断并丢弃，避免 hydration 阶段读取空 el 报错（对应 issue #23232）。

Props 详解

<NuxtPage> 的 Props 在源码 page.ts 中有完整的类型声明与运行时定义，汇总如下：

Prop	类型	作用说明
name	string	告诉 <RouterView> 渲染匹配路由记录 components 选项中对应名称的组件。配合"命名视图"使用，对应 [e-mail] 的命名文件约定（见页面目录文档的 Named Views 一节）
route	RouteLocationNormalized	所有组件都已解析完毕的路由位置对象
pageKey	string 或 (route) => string	控制 <NuxtPage> 何时被重新渲染
transition	boolean 或 TransitionProps	为通过该 <NuxtPage> 渲染的所有页面定义全局过渡
keepalive	boolean 或 KeepAliveProps	控制通过该 <NuxtPage> 渲染的页面状态保持

运行时类型校验与文档一致：transition 接受 Boolean / Object，keepalive 同样接受 Boolean / Object，pageKey 接受 Function / String（默认 null）。

除了显式 Props，Nuxt 会自动解析 name 与 route：因为页面系统会扫描并渲染 app/pages/ 目录下所有 Vue 组件文件，并将每个组件与对应的路由记录自动关联起来。

pageKey：控制页面组件的重新渲染

pageKey 用于控制 <NuxtPage> 何时重新渲染页面组件。理解它最直接的方式是看示例。

如果传入一个恒定不变的 key，<NuxtPage> 只会在首次挂载时渲染一次：

<template>
  <NuxtPage page-key="static" />
</template>

也可以基于当前路由使用动态 key：

<NuxtPage :page-key="route => route.fullPath" />

⚠️ 官方文档特别警告：不要在这里使用 $route 对象，因为它会干扰 <NuxtPage> 基于 <Suspense> 的页面渲染机制，可能引发渲染异常。

除了组件上直接传 Prop，pageKey 也可以在页面组件的 <script> 中通过 definePageMeta 以 key 字段传入：

<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,
})
</script>

关于 pageKey 的默认行为，可以从工具函数 packages/nuxt/src/pages/runtime/utils.ts 的 generateRouteKey 中看出端倪：当没有显式传入 pageKey、路由也没有 meta.key 时，Nuxt 默认基于路由匹配到的路径（将 :param 等动态段替换为实际参数值）生成 key——这意味着默认情况下，同一个页面组件在不同参数（如 /users/1 与 /users/2）之间切换会被判定为不同 key 而触发重渲染。用 key: route => route.fullPath 显式定义则可以让 key 精确跟随完整路径。

另外在客户端，当 pageKey 发生变化时，源码会通过 watcher 触发 page:loading:start Hook（见 page.ts 第 83-89 行），并在页面 resolve 后依次触发 page:finish 与 page:loading:end，从而实现与 useLoadingIndicator 加载进度条的联动。

获取页面组件实例：ref 与 pageRef

由于 <NuxtPage> 内部有多层包装，直接给 <NuxtPage> 绑 ref 拿到的并不是页面组件本身，而是 <NuxtPage> 组件实例。Nuxt 通过 expose({ pageRef }) 将真正渲染的页面组件实例暴露出来，因此需要通过 ref.value.pageRef 访问。

<script setup lang="ts">
const page = ref()

function logFoo () {
  page.value.pageRef.foo()
}
</script>

<template>
  <NuxtPage ref="page" />
</template>

对应的页面组件需要把方法暴露出去，才能被外部调用：

<script setup lang="ts">
const foo = () => {
  console.log('foo method called')
}

defineExpose({
  foo,
})
</script>

源码实现中，pageRef 定义于 setup 中并通过 expose({ pageRef }) 暴露，同时通过 RouteProvider 的 vnodeRef 传入并作为页面 vnode 的 ref 绑定（见 route-provider.ts 第 73 行 h(props.vnode, { ref: props.vnodeRef })），从而保证 pageRef 始终指向实际渲染的页面组件实例。

向页面透传自定义 Props

<NuxtPage> 除了上述内置 Props 外，还接受任何自定义 Props，并会把它们继续向下传递到页面组件。

例如在布局入口传入一个自定义 Prop foobar：

<template>
  <NuxtPage :foobar="123" />
</template>

在页面组件中可以通过 defineProps 正常接收：

<script setup lang="ts">
const props = defineProps<{ foobar: number }>()

console.log(props.foobar) // 输出: 123
</script>

如果页面组件没有用 defineProps 声明该 Prop，仍然可以通过 attrs（useAttrs()）拿到透传值：

<script setup lang="ts">
const attrs = useAttrs()
console.log(attrs.foobar) // 输出: 123
</script>

这在实现"布局统一注入页面公共参数"（如页面标题 key、分区标识等）时非常实用。值得一提的是，源码中 <NuxtPage> 设置了 inheritAttrs: false，并在渲染时把除内置 Props 外的 attrs 原样展开传给 <RouterView>（h(RouterView, { ..., ...attrs }, ...)），再经由插槽与 RouteProvider 传递到页面 vnode，这正是自定义 Props 能够一路透传到页面组件的底层原因。

源码中的配套实现与测试

围绕 <NuxtPage>，当前仓库的源码与测试形成了完整的印证链条：

• 组件主实现：packages/nuxt/src/pages/runtime/page.ts —— 涵盖 Props 声明、Suspense 包装、transition/keepalive 合并与优先级、suspenseKey 重挂载策略、page:start / page:finish / page:loading:end 等 Hook 触发、hydration 期间错误 Hook 的注册等。
• 路由 key 与 KeepAlive 工具：packages/nuxt/src/pages/runtime/utils.ts —— generateRouteKey（默认 key 推导与 pageKey 覆盖）、wrapInKeepAlive。
• 页面级响应式 route 提供者：packages/nuxt/src/app/components/route-provider.ts —— RouteProvider 通过 provide(PageRouteSymbol, ...) 向页面提供派生自当前渲染分叉的 route，并承担 pageRef 绑定。
• 过渡合并工具：packages/nuxt/src/app/components/utils.ts —— _mergeTransitionProps 与 _wrapInTransition。
• 全局默认配置：packages/schema/src/config/app.ts —— app.pageTransition: false 与 app.keepalive: false 的默认值。
• 端到端测试：test/nuxt/nuxt-page.test.ts —— 覆盖不同嵌套深度路由下 <NuxtPage> 的挂载行为、setup/render 次数统计等，可作为理解其生命周期语义的补充材料（该测试文件超过 1100 行，还包含多层级嵌套与异步 setup 场景的回归用例）。

若需要进一步了解页面文件到路由的映射关系、命名视图 [e-mail] 约定以及 definePageMeta 的全部可用字段，可继续阅读 页面目录文档 与 definePageMeta 工具文档。