---
title: "模板"
description: "Nuxt Kit 提供了一组实用工具来帮助你处理模板。这些函数允许你在开发和构建时生成额外的文件。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/kit/templates"
---
# 模板

> Nuxt Kit 提供了一组实用工具来帮助你处理模板。这些函数允许你在开发和构建时生成额外的文件。

模板允许你在开发和构建时生成额外的文件。这些文件将在虚拟文件系统中可用，并可在插件、布局、组件等中使用。`addTemplate` 和 `addTypeTemplate` 允许你向 Nuxt 应用添加模板。`updateTemplates` 允许你重新生成与筛选器匹配的模板。

## `addTemplate`

在构建期间将给定模板渲染到虚拟文件系统中，并可选地写入到项目的 `buildDir` 中

### 用法

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

export default defineNuxtModule({
  setup (options, nuxt) {
    const globalMeta = defu(nuxt.options.app.head, {
      charset: options.charset,
      viewport: options.viewport,
    })

    addTemplate({
      filename: 'meta.config.mjs',
      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
    })
  },
})
```

### 类型

```ts twoslash
// @errors: 2391
import type { NuxtTemplate, ResolvedNuxtTemplate } from '@nuxt/schema'
// ---cut---
function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate
```

### 参数

**template**：一个模板对象或指向模板的字符串路径。如果提供字符串，它将被转换为一个模板对象并将 `src` 设置为该字符串值。如果提供的是模板对象，则必须包含以下属性：

| 属性            | 类型                                                                                                              | 必填      | 描述                                                                                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `src`         | `string`                                                                                                        | `false` | 模板的路径。如果未提供 `src`，则必须提供 `getContents`。                                                                                                                                         |
| `filename`    | `string`                                                                                                        | `false` | 模板的文件名。如果未提供 `filename`，则会根据 `src` 路径生成。在这种情况下，必须提供 `src` 选项。                                                                                                                  |
| `dst`         | `string`                                                                                                        | `false` | 目标文件的路径。如果未提供 `dst`，则会根据 `filename` 路径和 Nuxt 的 `buildDir` 选项生成。                                                                                                                |
| `options`     | `Options`                                                                                                       | `false` | 传递给模板的选项。                                                                                                                                                                      |
| `getContents` | `(data: Options) => string \| Promise<string>`{lang="ts"}                                                       | `false` | 一个将使用 `options` 对象调用的函数。它应返回一个字符串，或解析为字符串的 Promise。如果提供了 `src`，则会忽略此函数。                                                                                                        |
| `write`       | `boolean`                                                                                                       | `false` | 如果设置为 `true`，模板将被写入目标文件。否则，模板只会在虚拟文件系统中使用。                                                                                                                                     |
| `dependsOn`   | `Array<'pages' \| 'plugins'> \| ((change: { event, path }, ctx: { nuxt, app, options }) => boolean)`{lang="ts"} | `false` | 模板输出可能依赖的受监视输入，超出 `nuxt.options` 和应用的已解析结构。若模板从未读取受监视文件的内容，请设置为 `[]`，这样当文件发生变化但没有文件被添加或删除时，Nuxt 就可以在开发模式下跳过重新编译。若模板读取了这些源，请列出相应的已知键；或者传入一个函数，根据每次变化进行判断。未声明任何依赖的模板会在每次变化时重新生成。 |

### 示例

#### 为运行时插件创建虚拟文件

在此示例中，我们在模块中合并一个对象，并在运行时插件中使用该结果。

```ts twoslash [module.ts]
import { addTemplate, defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    const globalMeta = defu(nuxt.options.app.head, {
      charset: options.charset,
      viewport: options.viewport,
    })

    addTemplate({
      filename: 'meta.config.mjs',
      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
    })
  },
})
```

#### 在开发环境中跳过重新生成

默认情况下，Nuxt 会在每次受监视文件事件发生时重新编译模板，因为它无法知道模板读取了哪些内容。如果你的模板仅由配置和文件是否存在决定，请声明这一点，这样当文件被编辑时，Nuxt 就可以不处理它：

```ts twoslash [module.ts]
import { addTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    addTemplate({
      filename: 'my-module/config.mjs',
      dependsOn: [],
      getContents: () => 'export default ' + JSON.stringify(options),
    })
  },
})
```

如果模板读取了已知源，请通过键声明它们：

```ts
addTemplate({
  filename: 'my-module/routes.mjs',
  dependsOn: ['pages'],
  getContents: ({ app }) => generateRoutes(app.pages),
})
```

如果模板读取了 Nuxt 不知道的文件，例如你自行扫描的一组 YAML 文件，请改为传入一个函数：

```ts
addTemplate({
  filename: 'my-module/content.mjs',
  dependsOn: ({ path }) => path.endsWith('.yaml'),
  getContents: () => generateContents(),
})
```

在上述模块中，我们生成了一个名为 `meta.config.mjs` 的虚拟文件。在运行时插件中，我们可以使用 `#build` 别名导入它：

```ts [runtime/plugin.ts]
import { createHead as createServerHead } from '@unhead/vue/server'
import { createHead as createClientHead } from '@unhead/vue/client'
import { defineNuxtPlugin } from '#imports'
// @ts-expect-error - virtual file
import metaConfig from '#build/meta.config.mjs'

export default defineNuxtPlugin((nuxtApp) => {
  const createHead = import.meta.server ? createServerHead : createClientHead
  const head = createHead()
  head.push(metaConfig.globalMeta)

  nuxtApp.vueApp.use(head)
})
```

## `addTypeTemplate`

在构建期间将给定模板渲染到项目的 buildDir 中，然后将其注册为类型声明。

### 用法

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

export default defineNuxtModule({
  setup () {
    addTypeTemplate({
      filename: 'types/markdown.d.ts',
      getContents: () => `declare module '*.md' {
  import type { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}`,
    })
  },
})
```

### 类型

```ts
function addTypeTemplate (template: NuxtTypeTemplate | string, context?: { nitro?: boolean, nuxt?: boolean }): ResolvedNuxtTemplate
```

### 参数

**template**：一个模板对象或指向模板的字符串路径。如果提供字符串，它将被转换为一个模板对象并将 `src` 设置为该字符串值。如果提供的是模板对象，则必须包含以下属性：

| 属性            | 类型                                                        | 必填      | 描述                                                                       |
| ------------- | --------------------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `src`         | `string`                                                  | `false` | 模板的路径。如果未提供 `src`，则必须提供 `getContents`。                                   |
| `filename`    | `string`                                                  | `false` | 模板的文件名。如果未提供 `filename`，将根据 `src` 路径生成。在这种情况下，`src` 选项是必需的。              |
| `dst`         | `string`                                                  | `false` | 目标文件的路径。如果未提供 `dst`，将根据 `filename` 路径和 nuxt 的 `buildDir` 选项生成。           |
| `options`     | `Options`                                                 | `false` | 传递给模板的选项。                                                                |
| `getContents` | `(data: Options) => string \| Promise<string>`{lang="ts"} | `false` | 一个将使用 `options` 对象调用的函数。它应返回一个字符串或一个解析为字符串的 Promise。如果提供了 `src`，此函数将被忽略。 |

**context**：可以传入一个可选的上下文对象来控制类型被添加的位置。如果省略，类型将仅添加到 Nuxt 上下文。该对象支持以下属性：

| 属性      | 类型        | 必填      | 描述                              |
| ------- | --------- | ------- | ------------------------------- |
| `nuxt`  | `boolean` | `false` | 如果设置为 `true`，类型将被添加到 Nuxt 上下文。  |
| `nitro` | `boolean` | `false` | 如果设置为 `true`，类型将被添加到 Nitro 上下文。 |

### 示例

#### 将类型模板添加到 Nitro 上下文

默认情况下，仅将类型声明添加到 Nuxt 上下文。要同时将它们添加到 Nitro 上下文，请将 nitro 设置为 true。

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

export default defineNuxtModule({
  setup () {
    addTypeTemplate({
      filename: 'types/auth.d.ts',
      getContents: () => `declare module '#auth-utils' {
  interface User {
    id: string;
    name: string;
  }

}`,
    }, {
      nitro: true,
    })
  },
})
```

这允许在 Nitro 上下文中使用 `#auth-utils` 模块。

```ts [server/api/auth.ts]
import type { User } from '#auth-utils'

export default eventHandler(() => {
  const user: User = {
    id: '123',
    name: 'John Doe',
  }

  // 使用该用户执行某些操作

  return user
})
```

## `addServerTemplate`

添加一个虚拟文件，该文件可在 Nuxt Nitro 服务端构建中使用。

### 用法

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

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })
  },
})
```

### 类型

```ts twoslash
// @errors: 2391
import type { NuxtServerTemplate } from '@nuxt/schema'
// ---cut---
function addServerTemplate (template: NuxtServerTemplate): NuxtServerTemplate
```

### 参数

**template**：一个模板对象。它必须具有以下属性：

| 属性            | 类型                                           | 必需     | 描述                                                   |
| ------------- | -------------------------------------------- | ------ | ---------------------------------------------------- |
| `filename`    | `string`                                     | `true` | 模板的文件名。                                              |
| `getContents` | `() => string \| Promise<string>`{lang="ts"} | `true` | 一个函数，将使用 `options` 对象调用。它应返回一个字符串或一个解析为字符串的 Promise。 |

### 示例

### 为 Nitro 创建一个虚拟文件

在此示例中，我们创建一个可在 Nuxt Nitro 服务端构建中使用的虚拟文件。

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

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })
  },
})
```

然后在运行时文件中

```ts [server/api/test.ts]
import { test } from '#my-module/test.js'

export default eventHandler(() => {
  return test
})
```

## `updateTemplates`

重新生成与筛选器匹配的模板。如果未提供筛选器，则将重新生成所有模板。

### 用法

```ts
import { defineNuxtModule, updateTemplates } from '@nuxt/kit'
import { resolve } from 'pathe'

export default defineNuxtModule({
  setup (options, nuxt) {
    const updateTemplatePaths = [
      resolve(nuxt.options.srcDir, 'pages'),
    ]
    // 当其中一个页面发生变化时，监听并重新构建路由模板列表
    nuxt.hook('builder:watch', async (event, relativePath) => {
      if (event === 'change') {
        return
      }

      const path = resolve(nuxt.options.srcDir, relativePath)
      if (updateTemplatePaths.some(dir => path.startsWith(dir))) {
        await updateTemplates({
          filter: template => template.filename === 'routes.mjs',
        })
      }
    })
  },
})
```

### 类型

```ts
async function updateTemplates (options: UpdateTemplatesOptions): void
```

### 参数

**options**: 传递给模板的选项。该对象可以具有以下属性：

| 属性       | 类型                                                       | 必需      | 描述                                                                           |
| -------- | -------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `filter` | `(template: ResolvedNuxtTemplate) => boolean`{lang="ts"} | `false` | 一个将使用 `template` 对象调用的函数。它应返回一个布尔值，用于指示是否应重新生成该模板。如果未提供 `filter`，则将重新生成所有模板。 |

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/template.ts)


## Sitemap

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