---
title: "Nuxt 生命周期"
description: "了解 Nuxt 应用的生命周期可以帮助你更深入地理解框架的工作原理，尤其是在服务端和客户端渲染两方面。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/nuxt-lifecycle"
---
# Nuxt 生命周期

> 了解 Nuxt 应用的生命周期可以帮助你更深入地理解框架的工作原理，尤其是在服务端和客户端渲染两方面。

本章的目标是提供对框架不同部分、高级执行顺序及其协同工作的概览。

## 服务器端

在服务器上，每个对应用的初始请求都会执行以下步骤：

### 第 1 步：设置 Nitro 服务器和 Nitro 插件（仅执行一次）

Nuxt 由[现代服务器引擎 Nitro](https://nitro.build/)驱动。

Nitro 启动时，会初始化并执行 [`/server/plugins`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/server#server-plugins) 目录下的插件。这些插件可以：

- 捕获并处理应用级错误。
- 注册在 Nitro 关闭时执行的钩子。
- 注册请求生命周期事件的钩子，例如修改响应。

::callout{icon="i-lucide-lightbulb"}
Nitro 插件只在服务器启动时执行一次。在无服务器环境中，服务器会在每个请求时启动，Nitro 插件也会随之启动，但这些插件不会被等待执行完成。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/server#server-plugins"}
::

### 第 2 步：Nitro 服务器中间件

初始化 Nitro 服务器后，每个请求都会执行 `server/middleware/` 目录下的中间件。中间件可以用于身份验证、日志记录或请求转换等任务。

::warning
从中间件返回一个值将终止请求并将该值作为响应发送。一般应避免这种行为，以确保请求被正确处理！
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/server#server-middleware"}
::

### 第 3 步：初始化 Nuxt 并执行 Nuxt 应用插件

首先创建 Vue 和 Nuxt 实例。接着，Nuxt 执行其服务器插件，包括：

- 内置插件，如 Vue Router 和 `unhead`。
- 位于 `plugins/` 目录下的自定义插件，包括无后缀的（例如 `myPlugin.ts`）和带有 `.server` 后缀的（例如 `myServerPlugin.server.ts`）插件。

插件按照特定顺序执行，并且可能依赖彼此。有关更多详情，包括执行顺序和并行执行，请参阅[插件文档](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/plugins)。

::callout{icon="i-lucide-lightbulb"}
此步骤之后，Nuxt 会调用 [`app:created`](https://nuxt.zhcndoc.com/docs/3.x/api/advanced/hooks#app-hooks-runtime) 钩子，可用于执行其他逻辑。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/plugins"}
::

### 第 4 步：路由验证

在初始化插件和执行中间件之前，若在 `definePageMeta` 函数中定义了 `validate` 方法，Nuxt 将调用它。`validate` 方法可以是同步或异步的，通常用于验证动态路由参数。

- 当参数有效时，`validate` 函数应返回 `true`。
- 验证失败时，应返回 `false` 或包含 `statusCode` 和/或 `statusMessage` 的对象以终止请求。

更多信息，请参阅[路由验证文档](https://nuxt.zhcndoc.com/docs/3.x/getting-started/routing#route-validation)。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/getting-started/routing#route-validation"}
::

### 第 5 步：执行 Nuxt 应用中间件

中间件允许你在导航到特定路由前运行代码，常用于身份验证、重定向或日志记录。

Nuxt 中有三种中间件：

- **全局路由中间件**
- **命名路由中间件**
- **匿名（或内联）路由中间件**

Nuxt 会自动执行应用首次进入时及每次路由导航前的全局中间件。命名和匿名中间件仅在对应页面组件中通过 `middleware` 属性指定的路由上执行。

有关各类型的详情和示例，请参阅[中间件文档](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/middleware)。

任何在服务器上的重定向都会向浏览器发送 `Location:` 头，浏览器随后会对新地址发起新的请求。发生此情况时，所有应用状态将被重置，除非以 Cookie 形式持久保存。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/middleware"}
::

### 第 6 步：渲染页面和组件

Nuxt 会渲染页面及其组件，并使用 `useFetch` 和 `useAsyncData` 获取所需数据。由于服务器端不存在动态更新和 DOM 操作，Vue 生命周期钩子如 `onBeforeMount`、`onMounted` 及后续钩子**不会**在 SSR 中执行。

默认情况下，Vue 在 SSR 期间暂停依赖追踪以提升性能。

::callout{icon="i-lucide-lightbulb"}
服务器端无响应性，因为 Vue SSR 是自顶向下将应用渲染为静态 HTML，无法回头修改已经渲染的内容。
::

::important
应避免在 `<script setup>` 的根作用域中书写需清理的副作用代码。例如使用 `setInterval` 设置定时器。在仅客户端代码中，我们可能在 `onBeforeUnmount` 或 `onUnmounted` 钩子中销毁定时器，但 SSR 期间这些卸载钩子不会被调用，定时器会永久存在。为避免此问题，应将副作用代码放入 `onMounted` 中。
::

::tip{icon="i-lucide-video" to="https://youtu.be/dZSNW07sO-A" target="_blank"}
观看 Daniel Roe 讲解服务器渲染和全局状态的视频。
::

### 第 7 步：生成 HTML 输出

所有数据获取完成并渲染组件后，Nuxt 会结合 `unhead` 的配置生成完整的 HTML 文档。此 HTML 及相关数据随后发送回客户端，完成 SSR 流程。

::callout{icon="i-lucide-lightbulb"}
将 Vue 应用渲染为 HTML 后，Nuxt 会调用 [`app:rendered`](https://nuxt.zhcndoc.com/docs/3.x/api/advanced/hooks#app-hooks-runtime) 钩子。
::

::callout{icon="i-lucide-lightbulb"}
在完成并发送 HTML 之前，Nitro 会调用 [`render:html`](https://nuxt.zhcndoc.com/docs/3.x/api/advanced/hooks#nitro-app-hooks-runtime-server-side) 钩子。此钩子允许你操作生成的 HTML，例如注入其他脚本或修改 meta 标签。
::

## 客户端（浏览器）

无论你选择何种 Nuxt 模式，此部分生命周期都会在浏览器中完整执行。

### 第 1 步：初始化 Nuxt 并执行 Nuxt 应用插件

此步骤与服务器端执行类似，包含内置和自定义插件。

`plugins/` 目录下的客户端插件会在客户端执行，包括无后缀的插件（如 `myPlugin.ts`）和带 `.client` 后缀的插件（如 `myClientPlugin.client.ts`）。

::callout{icon="i-lucide-lightbulb"}
此步骤之后，Nuxt 会调用 [`app:created`](https://nuxt.zhcndoc.com/docs/3.x/api/advanced/hooks#app-hooks-runtime) 钩子，可用于执行其他逻辑。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/plugins"}
::

### 第 2 步：路由验证

此步骤与服务器端执行相同，包含在 `definePageMeta` 函数中定义的 `validate` 方法。

### 第 3 步：执行 Nuxt 应用中间件

Nuxt 中间件会在服务器和客户端执行。若希望代码在特定环境运行，可考虑利用 `import.meta.client`（客户端）和 `import.meta.server`（服务器）进行拆分。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/middleware#when-middleware-runs"}
::

### 第 4 步：挂载 Vue 应用及 Hydration

调用 `app.mount('#__nuxt')` 会将 Vue 应用挂载到 DOM。如果应用使用 SSR 或 SSG 模式，Vue 会执行 hydration 步骤，使客户端应用具有交互性。在 hydration 期间，Vue 会重新创建应用（不包括 [Server Components](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/components#server-components)），将每个组件与其对应的 DOM 节点匹配，并附加 DOM 事件监听器。

为保证 hydration 正确性，服务器和客户端数据需保持一致。对于 API 请求，推荐使用 `useAsyncData`、`useFetch` 或其他 SSR 友好的组合函数，这些方法确保服务端获取的数据在 hydration 时复用，避免重复请求。新请求应仅在 hydration 后触发，防止 hydration 出错。

::callout{icon="i-lucide-lightbulb"}
挂载 Vue 应用之前，Nuxt 会调用 [`app:beforeMount`](https://nuxt.zhcndoc.com/docs/3.x/api/advanced/hooks#app-hooks-runtime) 钩子。
::

::callout{icon="i-lucide-lightbulb"}
挂载 Vue 应用之后，Nuxt 会调用 [`app:mounted`](https://nuxt.zhcndoc.com/docs/3.x/api/advanced/hooks#app-hooks-runtime) 钩子。
::

### 第 5 步：Vue 生命周期

与服务器不同，浏览器会执行完整的 [Vue 生命周期](https://vuejs.org/guide/essentials/lifecycle)。


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.