---
title: "模块"
description: "Nuxt Kit 提供了一组实用工具来帮助你创建和使用模块。你可以使用这些工具创建自定义模块或重用现有模块。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/kit/modules"
---
# 模块

> Nuxt Kit 提供了一组实用工具来帮助你创建和使用模块。你可以使用这些工具创建自定义模块或重用现有模块。

模块是 Nuxt 的构建块。Kit 提供了一组工具，帮助您创建和使用模块。您可以使用这些工具创建自己的模块或重用现有模块。例如，您可以使用 `defineNuxtModule` 函数定义一个模块，并使用 `moduleDependencies` 选项指定依赖关系。

## `defineNuxtModule`

定义一个 Nuxt 模块，自动将默认值与用户提供的选项合并，安装任何提供的钩子，并调用可选的 setup 函数以获得完全控制。

### 使用方法

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  defaults: {
    enabled: true,
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  },
})
```

### 类型

```tstwoslash
// @errors: 2391
import type { ModuleDefinition, ModuleOptions, NuxtModule } from '@nuxt/schema'
// ---cut---
export function defineNuxtModule<TOptions extends ModuleOptions> (
  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
): NuxtModule<TOptions, TOptions, false>

export function defineNuxtModule<TOptions extends ModuleOptions> (): {
  with: <TOptionsDefaults extends Partial<TOptions>> (
    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>,
  ) => NuxtModule<TOptions, TOptionsDefaults, true>
}
```

### 参数

**definition**：一个模块定义对象或模块函数。模块定义对象应包含以下属性：

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必需
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        meta
      </code>
    </td>
    
    <td>
      <code>
        ModuleMeta
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      模块的元数据。它定义模块名称、版本、配置键和兼容性。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        defaults
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          T
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          (
        </span>
        
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          nuxt
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Nuxt
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          T)
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      模块的默认选项。如果提供的是函数，则会将 Nuxt 实例作为第一个参数传入并调用。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema
      </code>
    </td>
    
    <td>
      <code>
        T
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      模块选项的 Schema。如果提供了 Schema，选项将应用于该 Schema。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hooks
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Partial
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          NuxtHooks
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      要为模块安装的钩子。如果提供了钩子，模块将安装这些钩子。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        moduleDependencies
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Record
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="sZSNi">
          ModuleDependency
        </span>
        
        <span class="sDfIl">
          >
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          (
        </span>
        
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          nuxt
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Nuxt
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          Record
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="sZSNi">
          ModuleDependency
        </span>
        
        <span class="sDfIl">
          >
        </span>
        
        <span class="sZSNi">
          )
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      对其他模块的依赖关系，包括版本约束和配置。可以是一个对象，也可以是一个接收 Nuxt 实例的函数。请参阅<a href="https://nuxt.zhcndoc.com/docs/4.x/api/kit/modules#specifying-module-dependencies">
        示例
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onInstall
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          nuxt
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Nuxt
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          Awaitable
        </span>
        
        <span class="sDfIl">
          <void>
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      首次安装模块时调用的生命周期钩子。需要定义 <code>
        meta.name
      </code>
      
       和 <code>
        meta.version
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onUpgrade
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          nuxt
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Nuxt
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="s1nJG">
          options
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          T
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="s1nJG">
          previousVersion
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          string
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          Awaitable
        </span>
        
        <span class="sDfIl">
          <void>
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      将模块升级到较新版本时调用的生命周期钩子。需要定义 <code>
        meta.name
      </code>
      
       和 <code>
        meta.version
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setup
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s8R28">
          this
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          void
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="s1nJG">
          resolvedOptions
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          T
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="s1nJG">
          nuxt
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Nuxt
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          Awaitable
        </span>
        
        <span class="sDfIl">
          <void
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sbKd-">
          false
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          ModuleSetupInstallResult
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      模块的 setup 函数。如果提供了该函数，模块将调用它。
    </td>
  </tr>
</tbody>
</table>

### 示例

#### 使用 `configKey` 使你的模块可配置

在定义 Nuxt 模块时，你可以设置 `configKey` 来指定用户应如何在他们的 `nuxt.config` 中配置该模块。

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  defaults: {
    // 模块选项
    enabled: true,
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  },
})
```

用户可以在 `nuxt.config` 中的对应键下为该模块提供选项。

```ts
export default defineNuxtConfig({
  myModule: {
    enabled: false,
  },
})
```

用户也可以通过将配置键设置为 `false` 来完全禁用模块。这样可以防止模块的 setup 函数运行，同时仍然为模块选项生成类型。

```ts
export default defineNuxtConfig({
  // 完全禁用该模块
  myModule: false,
})
```

<tip>

当你想禁用从 [Nuxt layers](https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/layers#disabling-modules-from-layers) 继承的模块时，这尤其有用。

</tip>

#### 定义模块的兼容性要求

如果你正在开发 Nuxt 模块并使用仅在特定 Nuxt 版本中受支持的 API，强烈建议包含 `compatibility.nuxt`。

```ts
export default defineNuxtModule({
  meta: {
    name: '@nuxt/icon',
    configKey: 'icon',
    compatibility: {
      // 需要的 Nuxt 版本，使用 semver 格式
      nuxt: '>=3.0.0', // 或使用 '^3.0.0'
    },
  },
  setup () {
    const resolver = createResolver(import.meta.url)
    // 实现模块逻辑
  },
})
```

如果用户尝试在与模块不兼容的 Nuxt 版本中使用你的模块，他们将在控制台收到警告。

```terminal
WARN  Module @nuxt/icon is disabled due to incompatibility issues:
 - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0
```

#### 通过 `.with()` 获得已解析选项的类型安全

当你需要对已解析/合并的模块选项进行类型安全检查时，可以使用 `.with()` 方法。它使 TypeScript 能够正确推断模块的默认值与传入 setup 函数的最终已解析选项之间的关系。

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

// 定义你的模块选项接口
interface ModuleOptions {
  apiKey: string
  baseURL: string
  timeout?: number
  retries?: number
}

export default defineNuxtModule<ModuleOptions>().with({
  meta: {
    name: '@nuxtjs/my-api',
    configKey: 'myApi',
  },
  defaults: {
    baseURL: 'https://api.example.com',
    timeout: 5000,
    retries: 3,
  },
  setup (resolvedOptions, nuxt) {
    // resolvedOptions 的类型正确推断为:
    // {
    //   apiKey: string          // 必填，无默认值
    //   baseURL: string         // 必填，具有默认值
    //   timeout: number         // 可选，具有默认值
    //   retries: number         // 可选，具有默认值
    // }

    console.log(resolvedOptions.baseURL) // ✅ TypeScript 知道它始终定义
    console.log(resolvedOptions.timeout) // ✅ TypeScript 知道它始终定义
    console.log(resolvedOptions.retries) // ✅ TypeScript 知道它始终定义
  },
})
```

不使用 `.with()` 时，`resolvedOptions` 参数将被类型化为原始的 `ModuleOptions` 接口，其中 `timeout` 和 `retries` 即使提供了默认值也可能为 `undefined`。`.with()` 方法使 TypeScript 能够理解默认值会使这些属性在已解析选项中变为非可选。

#### 使用生命周期钩子进行模块安装和升级

你可以定义在模块首次安装或升级到新版本时运行的生命周期钩子。这些钩子对于执行一次性的设置任务、数据库迁移或清理操作非常有用。

<important>

要使生命周期钩子正常工作，你**必须**在模块定义中提供 `meta.name` 和 `meta.version`。钩子使用这些值在项目的 `.nuxtrc` 文件中跟踪模块的安装状态。

</important>

生命周期钩子在主 `setup` 函数之前运行，如果钩子抛出错误，会记录该错误但不会中断构建过程。

**onInstall** 仅在模块第一次被添加到项目时运行一次。

**onUpgrade** 在每次模块版本提升（使用 semver 比较）时运行——但对于每个版本提升只运行一次。

##### 示例

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

export default defineNuxtModule({
  meta: {
    name: 'my-awesome-module',
    version: '1.2.0', // 生命周期钩子所需
    configKey: 'myAwesomeModule',
  },
  defaults: {
    apiKey: '',
    enabled: true,
  },

  onInstall (nuxt) {
    // 仅在模块首次安装时运行
    console.log('Setting up my-awesome-module for the first time!')

    // 你可能想：
    // - 创建初始配置文件
    // - 设置数据库模式
    // - 显示欢迎信息
    // - 执行初始数据迁移
  },

  onUpgrade (nuxt, options, previousVersion) {
    // 当模块升级到新版本时运行
    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)

    // 你可能想：
    // - 迁移配置文件
    // - 更新数据库模式
    // - 清理已弃用的文件
    // - 显示升级说明

    if (isLess(previousVersion, '1.1.0')) {
      console.log('⚠️  1.1.0 中的破坏性变更 - 请查看迁移指南')
    }
  },

  setup (options, nuxt) {
    // 常规 setup 逻辑在每次构建时执行
    if (options.enabled) {
      // 配置模块
    }
  },
})
```

#### 指定模块依赖

您可以使用 `moduleDependencies` 选项来声明对其他模块的依赖。这提供了一种可靠的方法来确保正确的设置顺序、版本兼容性和配置管理。

`moduleDependencies` 选项可以是一个对象或一个接收 Nuxt 实例的函数：

##### 示例

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    '@nuxtjs/tailwindcss': {
      // 指定版本约束（semver 格式）
      version: '>=6.0.0',
      // 覆盖用户设置的配置
      overrides: {
        exposeConfig: true,
      },
      // 设置默认值，但尊重用户设置
      defaults: {
        config: {
          darkMode: 'class',
        },
      },
    },
    '@nuxtjs/fontaine': {
      // 可选依赖不会被安装，但如果安装了，则确保可以设置其选项
      optional: true,
      defaults: {
        fonts: [
          {
            family: 'Roboto',
            fallbacks: ['Impact'],
          },
        ],
      },
    },
  },
  setup (options, nuxt) {

  },
})
```

您还可以使用一个函数根据 Nuxt 配置动态确定依赖项：

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies (nuxt) {
    const dependencies: Record<string, any> = {
      '@nuxtjs/tailwindcss': {
        version: '>=6.0.0',
      },
    }

    // 根据 Nuxt 配置有选择地添加依赖
    if (nuxt.options.experimental?.someFeature) {
      dependencies['@nuxtjs/fontaine'] = {
        optional: true,
      }
    }

    return dependencies
  },
  setup (options, nuxt) {
    // 你的 setup 逻辑将在所有依赖初始化后运行
  },
})
```

## `installModule`

<callout type="warning">

**已弃用：** 请改用 `defineNuxtModule` 中的 [`moduleDependencies`](https://nuxt.zhcndoc.com/docs/4.x/api/kit/modules#specifying-module-dependencies) 选项。`installModule` 函数将在未来版本中移除（或可能变为非阻塞）。

</callout>

以编程方式安装指定的 Nuxt 模块。这在您的模块依赖于其他模块时非常有用。您可以将模块选项作为对象传递给 `inlineOptions`，它们将被传递给模块的 `setup` 函数。

### 使用方法

```tstwoslash
import { defineNuxtModule, installModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup () {
    // 将安装 @nuxtjs/fontaine 并使用 Roboto 字体及 Impact 作为回退
    await installModule('@nuxtjs/fontaine', {
      // 模块配置
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        },
      ],
    })
  },
})
```

### 类型

```ts
async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
```

### 参数

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必需
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        moduleToInstall
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          NuxtModule
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      要安装的模块。可以是模块名称的字符串，或模块对象本身。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inlineOptions
      </code>
    </td>
    
    <td>
      <code>
        any
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      一个将传递给模块 <code>
        setup
      </code>
      
       函数的模块选项对象。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nuxt
      </code>
    </td>
    
    <td>
      <code>
        Nuxt
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Nuxt 实例。如果未提供，将通过 <code>
        useNuxt()
      </code>
      
       调用从上下文中检索。
    </td>
  </tr>
</tbody>
</table>

### 示例

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

export default defineNuxtModule({
  async setup (options, nuxt) {
    // 将安装 @nuxtjs/fontaine 并使用 Roboto 字体及 Impact 作为回退
    await installModule('@nuxtjs/fontaine', {
      // 模块配置
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        },
      ],
    })
  },
})
```

---

- [源码](https://github.com/nuxt/nuxt/tree/main/packages/kit/src/module)


## Sitemap

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