---
title: "生命周期钩子"
description: "Nuxt 提供了一个强大的钩子系统，可以通过钩子扩展几乎每个方面。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/advanced/hooks"
---
# 生命周期钩子

> Nuxt 提供了一个强大的钩子系统，可以通过钩子扩展几乎每个方面。

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/hooks"}
::

## App 钩子（运行时）

查看 [app 源代码](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts#L37) 以获取所有可用的钩子。

| 钩子                           | 参数                  | 环境              | 描述                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------- | ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app:created`                | `vueApp`            | Server & Client | 创建初始 `vueApp` 实例时调用。                                                                                                                                                                                                                                                                                                                                                                                      |
| `app:error`                  | `err`               | Server & Client | 发生致命错误时调用。                                                                                                                                                                                                                                                                                                                                                                                                |
| `app:error:cleared`          | `{ redirect? }`     | Server & Client | 发生致命错误时调用。                                                                                                                                                                                                                                                                                                                                                                                                |
| `vue:setup`                  | -                   | Server & Client | 初始化 Nuxt 根组件的设置时调用。此回调必须是同步的。                                                                                                                                                                                                                                                                                                                                                                             |
| `vue:error`                  | `err, target, info` | Server & Client | Vue 错误传播到根组件时调用。[了解更多](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured)。                                                                                                                                                                                                                                                                                                                  |
| `app:rendered`               | `renderContext`     | Server          | SSR 渲染完成时调用。                                                                                                                                                                                                                                                                                                                                                                                              |
| `app:redirected`             | -                   | Server          | SSR 重定向之前调用。                                                                                                                                                                                                                                                                                                                                                                                              |
| `app:beforeMount`            | `vueApp`            | Client          | 挂载应用之前调用，仅在客户端调用。                                                                                                                                                                                                                                                                                                                                                                                         |
| `app:mounted`                | `vueApp`            | Client          | Vue 应用在浏览器中初始化并挂载时调用。                                                                                                                                                                                                                                                                                                                                                                                     |
| `app:suspense:resolve`       | `appComponent`      | Client          | 在 [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) 解析事件时调用。                                                                                                                                                                                                                                                                                                                                |
| `app:manifest:update`        | `{ id, timestamp }` | Client          | 检测到应用有更新版本时调用。                                                                                                                                                                                                                                                                                                                                                                                            |
| `app:data:refresh`           | `keys?`             | Client          | 调用 `refreshNuxtData` 时调用。                                                                                                                                                                                                                                                                                                                                                                                 |
| `link:prefetch`              | `to`                | Client          | 观察到 `<NuxtLink>` 即将预取时调用。                                                                                                                                                                                                                                                                                                                                                                                 |
| `page:start`                 | `pageComponent?`    | Client          | 在 `NuxtPage` 内部的 [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) 触发 pending 事件时调用。                                                                                                                                                                                                                                                                                                        |
| `page:finish`                | `pageComponent?`    | Client          | 在 `NuxtPage` 内部的 [Suspense](https://vuejs.org/guide/built-ins/suspense#suspense) 触发 resolved 事件时调用。                                                                                                                                                                                                                                                                                                       |
| `page:loading:start`         | -                   | Client          | 路由导航开始时（解析之前）或页面键发生变化时调用。如果页面被复用（例如，在 `definePageMeta` 中使用静态 `key`），则可能不会重新运行页面组件的 `setup()`，但仍会触发此钩子。                                                                                                                                                                                                                                                                                                    |
| `page:loading:end`           | -                   | Client          | `page:finish` 之后调用                                                                                                                                                                                                                                                                                                                                                                                        |
| `page:transition:finish`     | `pageComponent?`    | Client          | 页面过渡的 [onAfterLeave](https://vuejs.org/guide/built-ins/transition#javascript-hooks) 事件触发后调用。                                                                                                                                                                                                                                                                                                              |
| `dev:ssr-logs`               | `logs`              | Client          | 接收到传递给客户端的服务器端日志数组时调用（如果启用了 `features.devLogs`）。                                                                                                                                                                                                                                                                                                                                                          |
| `page:view-transition:start` | `transition`        | Client          | 启用[实验性的 viewTransition 支持](https://nuxt.zhcndoc.com/docs/4.x/getting-started/transitions#view-transitions-api-experimental)时，在调用 `document.startViewTransition` 后调用。`transition` 参数是一个具有 `types` 属性（[`ViewTransitionTypeSet`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransitionTypeSet)）的 [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition) 对象，该属性可读取或修改。 |

## Nuxt 钩子（构建时）

查看 [schema 源代码](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts#L83) 以获取所有可用钩子。

| 钩子                          | 参数                                                       | 描述                                                                                                                                                         |
| --------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kit:compatibility`         | `compatibility, issues`                                  | 允许扩展兼容性检查。                                                                                                                                                 |
| `ready`                     | `nuxt`                                                   | Nuxt 初始化后、Nuxt 实例准备就绪可以运行时调用。                                                                                                                              |
| `close`                     | `nuxt`                                                   | Nuxt 实例正常关闭时调用。                                                                                                                                            |
| `restart`                   | `{ hard?: boolean }`                                     | 用于重启当前 Nuxt 实例。                                                                                                                                            |
| `modules:before`            | -                                                        | Nuxt 初始化期间，在安装用户模块之前调用。                                                                                                                                    |
| `modules:done`              | -                                                        | Nuxt 初始化期间，在安装用户模块之后调用。                                                                                                                                    |
| `module:before`             | `module`                                                 | 每个模块开始设置之前立即调用。                                                                                                                                            |
| `module:done`               | `module`                                                 | 每个模块设置完成后立即调用，并包含所耗费的时间。                                                                                                                                   |
| `app:resolve`               | `app`                                                    | 解析 `app` 实例后调用。                                                                                                                                            |
| `app:templates`             | `app`                                                    | 生成 `NuxtApp` 期间调用，以便自定义、修改或向构建目录添加新文件（虚拟添加或写入 `.nuxt`）。                                                                                                    |
| `app:templatesGenerated`    | `app`                                                    | 模板编译到[虚拟文件系统](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/nuxt)（vfs）后调用。                                                                         |
| `build:before`              | -                                                        | Nuxt bundle 构建器运行之前调用。                                                                                                                                     |
| `build:done`                | -                                                        | Nuxt bundle 构建器完成后调用。                                                                                                                                      |
| `build:manifest`            | `manifest`                                               | Vite 和 webpack 构建 manifest 期间调用。可用于自定义 Nitro 在最终 HTML 中用于渲染 `<script>` 和 `<link>` 标签的 manifest。                                                            |
| `builder:generateApp`       | `options`                                                | 生成应用之前调用。                                                                                                                                                  |
| `builder:watch`             | `event, path`                                            | 开发环境构建期间，监听器发现项目中的文件或目录发生变化时调用。                                                                                                                            |
| `pages:extend`              | `pages`                                                  | 从文件系统扫描页面路由后调用。                                                                                                                                            |
| `pages:resolved`            | `pages`                                                  | 扫描元数据并将其应用到页面路由后调用。                                                                                                                                        |
| `pages:routerOptions`       | `{ files: Array<{ path: string, optional?: boolean }> }` | 解析 `router.options` 文件时调用。数组中靠后的项会覆盖靠前的项。                                                                                                                  |
| `server:routes`             | `routes`, `context`                                      | Nuxt 需要获取服务器将提供的完整路由处理程序集合时调用，以便针对这些路由为 `$fetch` 和 `useFetch` 提供类型支持。                                                                                      |
| `server:devHandler`         | `handler`                                                | 在 Nitro 开发服务器上注册开发中间件时调用。                                                                                                                                  |
| `imports:sources`           | `presets`                                                | 设置期间调用，允许模块扩展来源。                                                                                                                                           |
| `imports:extend`            | `imports`                                                | 设置期间调用，允许模块扩展导入项。                                                                                                                                          |
| `imports:context`           | `context`                                                | 创建 [unimport](https://github.com/unjs/unimport) 上下文时调用。                                                                                                    |
| `imports:dirs`              | `dirs`                                                   | 允许扩展导入目录。                                                                                                                                                  |
| `components:dirs`           | `dirs`                                                   | 在 `app:resolve` 期间调用，以便扩展用于扫描可自动导入组件的目录。                                                                                                                   |
| `components:extend`         | `components`                                             | 允许扩展新组件。                                                                                                                                                   |
| `nitro:config`              | `nitroConfig`                                            | 初始化 Nitro 之前调用，允许自定义 Nitro 配置。                                                                                                                             |
| `nitro:init`                | `nitro`                                                  | Nitro 初始化后调用，可用于注册 Nitro 钩子并直接与 Nitro 交互。                                                                                                                  |
| `nitro:build:before`        | `nitro`                                                  | 构建 Nitro 实例之前调用。                                                                                                                                           |
| `nitro:build:public-assets` | `nitro`                                                  | 复制公共资源后调用。可在构建 Nitro 服务器之前修改公共资源。                                                                                                                          |
| `prerender:routes`          | `ctx`                                                    | 允许扩展要预渲染的路由。                                                                                                                                               |
| `build:error`               | `error`                                                  | 构建期间发生错误时调用。                                                                                                                                               |
| `prepare:types`             | `options`                                                | `@nuxt/cli` 写入 TypeScript 配置文件（`.nuxt/tsconfig.app.json`、`.nuxt/tsconfig.server.json` 等）和 `.nuxt/nuxt.d.ts` 之前调用，允许在 `nuxt.d.ts` 中添加自定义引用和声明，或直接修改生成配置中的选项 |
| `listen`                    | `listenerServer, listener`                               | 开发服务器加载时调用。                                                                                                                                                |
| `schema:extend`             | `schemas`                                                | 允许扩展默认 schema。                                                                                                                                             |
| `schema:resolved`           | `schema`                                                 | 允许扩展已解析的 schema。                                                                                                                                           |
| `schema:beforeWrite`        | `schema`                                                 | 写入给定 schema 之前调用。                                                                                                                                          |
| `schema:written`            | -                                                        | 写入 schema 后调用。                                                                                                                                             |
| `vite:extend`               | `viteBuildContext`                                       | 允许扩展 Vite 默认上下文。                                                                                                                                           |
| `vite:extendConfig`         | `viteInlineConfig, env`                                  | 允许扩展 Vite 默认配置。**在 Nuxt 5+ 中已弃用。**在 Nuxt 5 中，此钩子作用于共享配置，而非单独的客户端/服务器配置。                                                                                    |
| `vite:configResolved`       | `viteInlineConfig, env`                                  | 允许读取已解析的 Vite 配置。**在 Nuxt 5+ 中已弃用。**在 Nuxt 5 中，此钩子作用于共享配置，而非单独的客户端/服务器配置。                                                                                  |
| `vite:serverCreated`        | `viteServer, env`                                        | 创建 Vite 服务器时调用。                                                                                                                                            |
| `vite:compiled`             | -                                                        | Vite 服务器编译完成后调用。                                                                                                                                           |
| `webpack:config`            | `webpackConfigs`                                         | 配置 webpack 编译器之前调用。                                                                                                                                        |
| `webpack:configResolved`    | `webpackConfigs`                                         | 允许读取已解析的 webpack 配置。                                                                                                                                       |
| `webpack:compile`           | `options`                                                | 编译开始前立即调用。                                                                                                                                                 |
| `webpack:compiled`          | `options`                                                | 资源加载后调用。                                                                                                                                                   |
| `webpack:change`            | `shortPath`                                              | WebpackBar 触发 `change` 时调用。                                                                                                                                |
| `webpack:error`             | -                                                        | WebpackBar 触发 `done` 且存在错误时调用。                                                                                                                             |
| `webpack:done`              | -                                                        | WebpackBar 触发 `allDone` 时调用。                                                                                                                               |
| `webpack:progress`          | `statesArray`                                            | WebpackBar 触发 `progress` 时调用。                                                                                                                              |

## Nitro 应用钩子（运行时，服务端）

参考 [Nitro](https://nitro.build/guide/plugins#available-hooks) 获取所有可用钩子。

| 钩子                | 参数                                         | 描述                    | 类型                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ------------------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dev:ssr-logs`    | `{ path, logs }`                           | 服务器端                  | 请求周期结束时调用，带有传递给客户端的服务器日志数组。                                                                                                                                                                                                                                                                                                                                                                             |
| `render:response` | `response, { event }`                      | 在发送响应之前调用。            | [response](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L24), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)                                                                                                                                                         |
| `render:html`     | `html, { event }`                          | 在构建 HTML 之前调用。        | [html](https://github.com/nuxt/nuxt/blob/71ef8bd3ff207fd51c2ca18d5a8c7140476780c7/packages/nuxt/src/core/runtime/nitro/renderer.ts#L15), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)                                                                                                                                                             |
| `render:island`   | `islandResponse, { event, islandContext }` | 在构建 island HTML 之前调用。 | [islandResponse](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L28), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), [islandContext](https://github.com/nuxt/nuxt/blob/e50cabfed1984c341af0d0c056a325a8aec26980/packages/nuxt/src/core/runtime/nitro/renderer.ts#L38) |
| `close`           | -                                          | Nitro 关闭时调用。          | -                                                                                                                                                                                                                                                                                                                                                                                                       |
| `error`           | `error, { event? }`                        | 发生错误时调用。              | [error](https://github.com/nitrojs/nitro/blob/d20ffcbd16fc4003b774445e1a01e698c2bb078a/src/types/runtime/nitro.ts#L48), [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)                                                                                                                                                                              |
| `request`         | `event`                                    | 收到请求时调用。              | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38)                                                                                                                                                                                                                                                                                                      |
| `beforeResponse`  | `event, { body }`                          | 发送响应前调用。              | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown                                                                                                                                                                                                                                                                                             |
| `afterResponse`   | `event, { body }`                          | 发送响应后调用。              | [event](https://github.com/h3js/h3/blob/f6ceb5581043dc4d8b6eab91e9be4531e0c30f8e/src/types.ts#L38), unknown                                                                                                                                                                                                                                                                                             |


## Sitemap

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