---
title: "使用 Hooks 并扩展类型"
description: "掌握模块中的生命周期钩子、虚拟文件和 TypeScript 声明。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/guide/modules/recipes-advanced"
---
# 使用 Hooks 并扩展类型

> 掌握模块中的生命周期钩子、虚拟文件和 TypeScript 声明。

以下是编写模块的一些高级模式，包括钩子、模板和类型增强。

## 使用生命周期钩子

[生命周期钩子](https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/hooks) 允许你扩展 Nuxt 的几乎所有方面。模块可以通过编程方式绑定钩子，也可以通过其定义中的 `hooks` 映射绑定。

```js
import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  // 通过 `hooks` 映射绑定 `app:error` 钩子
  hooks: {
    'app:error': (err) => {
      console.info(`发生了这个错误: ${err}`)
    },
  },
  setup (options, nuxt) {
    // 以编程方式绑定 `pages:extend` 钩子
    nuxt.hook('pages:extend', (pages) => {
      console.info(`发现了 ${pages.length} 个页面`)
    })
  },
})
```

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/api/advanced/hooks"}
::

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/nuxt-lifecycle-hooks?friend=nuxt" target="_blank"}
观看 Vue School 关于在模块中使用 Nuxt 生命周期钩子的视频。
::

::note
**模块清理**
  

  

如果你的模块打开、处理或启动了某个 watcher，应该在 Nuxt 生命周期结束时关闭它。可以使用 `close` 钩子来实现此功能。

```ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async (nuxt) => {
      // 在此处添加你的自定义代码
    })
  },
})
```
::

### 创建自定义钩子

模块还可以定义和调用自己的钩子，这是一种让你的模块可扩展的强大模式。

如果你期望其他模块能够订阅你的模块钩子，应该在 `modules:done` 钩子中调用它们。这能保证所有其他模块都有机会完成设置，并在它们自己的 `setup` 函数中注册对你的钩子的监听器。

```ts
// my-module/module.ts
import { defineNuxtModule } from '@nuxt/kit'

export interface ModuleHooks {
  'my-module:custom-hook': (payload: { foo: string }) => void
}

export default defineNuxtModule({
  setup (options, nuxt) {
    // 在 `modules:done` 中调用你的钩子
    nuxt.hook('modules:done', async () => {
      const payload = { foo: 'bar' }
      await nuxt.callHook('my-module:custom-hook', payload)
    })
  },
})
```

## 添加虚拟文件

如果你需要添加一个可以被用户应用导入的虚拟文件，可以使用 `addTemplate` 工具。

```ts
import { addTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // 该文件被添加到 Nuxt 的内部虚拟文件系统中，可从 '#build/my-module-feature.mjs' 导入
    addTemplate({
      filename: 'my-module-feature.mjs',
      getContents: () => 'export const myModuleFeature = () => "hello world !"',
    })
  },
})
```

对于服务器端，应使用 `addServerTemplate` 工具。

```ts
import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // 该文件被添加到 Nitro 的虚拟文件系统，可以在服务器代码中通过 'my-server-module.mjs' 导入
    addServerTemplate({
      filename: 'my-server-module.mjs',
      getContents: () => 'export const myServerModule = () => "hello world !"',
    })
  },
})
```

## 更新虚拟文件

如果你需要更新你的模板/虚拟文件，可以利用 `updateTemplates` 工具，如下所示：

```ts
nuxt.hook('builder:watch', (event, path) => {
  if (path.includes('my-module-feature.config')) {
    // 这将重新加载你注册的模板
    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
  }
})
```

## 添加类型声明

你可能还想向用户项目添加类型声明（例如，用于增强 Nuxt 接口或提供你自己的全局类型）。为此，Nuxt 提供了 `addTypeTemplate` 工具，它既会将模板写入磁盘，也会在生成的 `nuxt.d.ts` 文件中添加对它的引用。

如果你的模块需要增强 Nuxt 处理的类型，你可以使用 `addTypeTemplate` 来执行此操作：

```js
import { addTemplate, addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `// 由 my-module 生成
        interface MyModuleNitroRules {
          myModule?: { foo: 'bar' }
        }
        declare module 'nitropack/types' {
          interface NitroRouteRules extends MyModuleNitroRules {}
          interface NitroRouteConfig extends MyModuleNitroRules {}
        }
        export {}`,
    })
  },
})
```

如果你需要更细粒度的控制，可以使用 `prepare:types` 钩子注册回调，用于注入你的类型。

```ts
const template = addTemplate({ /* 模板选项 */ })
nuxt.hook('prepare:types', ({ references }) => {
  references.push({ path: template.dst })
})
```

## 扩展 TypeScript 配置

从你的模块中，有多种方式可以扩展用户项目的 TypeScript 配置。

最简单的方式是直接修改 Nuxt 配置，如下所示：

<!-- @case-police-ignore tsConfig -->

```ts
// 扩展 tsconfig.app.json
nuxt.options.typescript.tsConfig.include ??= []
nuxt.options.typescript.tsConfig.include.push(resolve('./augments.d.ts'))

// 扩展 tsconfig.shared.json
nuxt.options.typescript.sharedTsConfig.include ??= []
nuxt.options.typescript.sharedTsConfig.include.push(resolve('./augments.d.ts'))

// 扩展 tsconfig.node.json
nuxt.options.typescript.nodeTsConfig.include ??= []
nuxt.options.typescript.nodeTsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.server.json
nuxt.options.typescript.serverTsConfig.include ??= []
nuxt.options.typescript.serverTsConfig.include.push(resolve('./augments.d.ts'))
```

或者，你也可以使用 `prepare:types` 和 `nitro:prepare:types` 钩子，分别扩展特定类型上下文的 TypeScript 引用，或像上面示例中那样修改 TypeScript 配置。

```ts
nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences }) => {
  // 扩展 app 上下文
  references.push({ path: resolve('./augments.d.ts') })
  // 扩展 shared 上下文
  sharedReferences.push({ path: resolve('./augments.d.ts') })
  // 扩展 node 上下文
  nodeReferences.push({ path: resolve('./augments.d.ts') })
})

nuxt.hook('nitro:prepare:types', ({ references }) => {
  // 扩展服务器上下文
  references.push({ path: resolve('./augments.d.ts') })
})
```

::note
TypeScript 引用会将文件添加到类型上下文中，[不会受到 `tsconfig.json` 中 `exclude` 选项的影响](https://www.typescriptlang.org/tsconfig/#exclude)。
::

## 类型增强

Nuxt 会自动将你的模块目录包含到适当的类型上下文中。要增强模块中的类型，你所需做的只是将类型声明文件放在基于增强类型上下文的相应目录。或者，你可以 [扩展 TypeScript 配置](#extend-typescript-config) 从任意位置进行增强。

- `my-module/runtime/` - app 类型上下文（不包括 `runtime/server` 目录）
- `my-module/runtime/server/` - 服务器类型上下文
- `my-module/` - node 类型上下文（不包括 `runtime/` 和 `runtime/server` 目录）

```bash [目录结构]
-| my-module/   # node 类型上下文
---| runtime/   # app 类型上下文
------| augments.app.d.ts
------| server/ # 服务器类型上下文
---------| augments.server.d.ts
---| module.ts
---| augments.node.d.ts
```

### 已知限制

#### 在 App 上下文中对服务器路由进行类型检查

服务器路由除了使用 `tsconfig.server.json`，还会使用 `tsconfig.app.json` 进行类型检查。

这是必需的，因为 Nuxt 会推断服务器端点的返回类型，以便在 [`$fetch`](https://nuxt.zhcndoc.com/docs/4.x/api/utils/dollarfetch) 和 [`useFetch`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-fetch) 中提供响应类型。

::warning
在路由文件中使用**仅限服务器端的类型**时，这可能会引发问题。例如，如果模块使用 [`addServerTemplate`](https://nuxt.zhcndoc.com/docs/4.x/api/kit/templates#addservertemplate) 创建仅限服务器端的虚拟文件，并在 `tsconfig.server.json` 中为其声明类型，那么这些类型声明将仅在服务器上下文中可用。当 app 上下文对服务器路由进行类型检查时，它无法识别这些仅限服务器端的类型，并会报告错误。要解决此问题，遗憾的是，你还需要在 app 上下文中声明这些类型。
::


## Sitemap

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