---
title: "构建器"
description: "Nuxt Kit 提供了一组实用工具，帮助您使用构建器。这些函数允许您扩展 Vite 和 webpack 的配置。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/api/kit/builder"
---
# 构建器

> Nuxt Kit 提供了一组实用工具，帮助您使用构建器。这些函数允许您扩展 Vite 和 webpack 的配置。

Nuxt 有基于 [Vite](https://github.com/nuxt/nuxt/tree/main/packages/vite) 和 [webpack](https://github.com/nuxt/nuxt/tree/main/packages/webpack) 的构建器。您可以使用 `extendViteConfig` 和 `extendWebpackConfig` 函数扩展传递给它们的配置。您还可以通过 `addVitePlugin`、`addWebpackPlugin` 和 `addBuildPlugin` 添加额外的插件。

## `extendViteConfig`

扩展 Vite 配置。回调函数可以被多次调用，应用于客户端和服务器构建。

::warning
此钩子现已弃用，建议改用带有 `config` 钩子的 Vite 插件，或者针对环境特定配置使用 `applyToEnvironment` 钩子。
::

### 用法

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

export default defineNuxtModule({
  setup () {
    extendViteConfig((config) => {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('cross-fetch')
    })
  },
})
```

Nuxt 5+ 中针对环境特定的配置，请改用 `addVitePlugin()`：

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

export default defineNuxtModule({
  setup () {
    // 全局配置（影响所有环境）
    addVitePlugin(() => ({
      name: 'my-global-plugin',
      config (config) {
        // 该钩子在环境设置之前运行
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('cross-fetch')
      },
    }))

    // 针对特定环境的配置
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      configEnvironment (name, config) {
        // 仅影响客户端环境
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('client-only-package')
      },
    }))
  },
})
```

::warning
**重要提示：** `config` 钩子在 `applyToEnvironment` 之前运行，修改的是全局配置。环境特定的配置修改请使用 `configEnvironment`。
::

### 类型

```ts twoslash
// @errors: 2391
import type { UserConfig as ViteConfig } from 'vite'
import type { ExtendViteConfigOptions } from '@nuxt/kit'
// ---cut---
function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
```

::read-more{to="https://vite.dev/config/" target="_blank" icon="i-simple-icons-vite"}
访问 Vite 官网以获取有关配置的更多信息。
::

### 参数

**`callback`**：将被调用并传入 Vite 配置对象的回调函数。

**`options`**：传递给回调函数的选项对象。该对象可以包含以下属性：

| 属性        | 类型        | 必须      | 描述                                                                                                  |
| --------- | --------- | ------- | --------------------------------------------------------------------------------------------------- |
| `dev`     | `boolean` | `false` | 如果设置为 `true`，回调函数将在开发模式构建时被调用。                                                                      |
| `build`   | `boolean` | `false` | 如果设置为 `true`，回调函数将在生产模式构建时被调用。                                                                      |
| `server`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建服务器包时被调用。**在 Nuxt 5+ 中已弃用。** 请改用带有 `applyToEnvironment()` 的 `addVitePlugin()`。 |
| `client`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建客户端包时被调用。**在 Nuxt 5+ 中已弃用。** 请改用带有 `applyToEnvironment()` 的 `addVitePlugin()`。 |
| `prepend` | `boolean` | `false` | 如果设置为 `true`，回调函数将用 `unshift()` 被添加至数组头部，而非使用 `push()` 添加至数组尾部。                                     |

## `extendWebpackConfig`

扩展 webpack 配置。回调函数可以被多次调用，应用于客户端和服务器构建。

### 用法

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

export default defineNuxtModule({
  setup () {
    extendWebpackConfig((config) => {
      config.module!.rules!.push({
        test: /\.txt$/,
        use: 'raw-loader',
      })
    })
  },
})
```

### 类型

```ts twoslash
// @errors: 2391
import type { Configuration as WebpackConfig } from 'webpack'
import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
// ---cut---
function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
```

::read-more{to="https://webpack.js.org/configuration/" target="_blank" icon="i-simple-icons-webpack"}
访问 webpack 官网以获取有关配置的更多信息。
::

### 参数

**`callback`**：将被调用并传入 webpack 配置对象的回调函数。

**`options`**：传递给回调函数的选项对象。该对象可以包含以下属性：

| 属性        | 类型        | 必须      | 描述                                                              |
| --------- | --------- | ------- | --------------------------------------------------------------- |
| `dev`     | `boolean` | `false` | 如果设置为 `true`，回调函数将在开发模式构建时被调用。                                  |
| `build`   | `boolean` | `false` | 如果设置为 `true`，回调函数将在生产模式构建时被调用。                                  |
| `server`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建服务器包时被调用。                                  |
| `client`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建客户端包时被调用。                                  |
| `prepend` | `boolean` | `false` | 如果设置为 `true`，回调函数将用 `unshift()` 被添加至数组头部，而非使用 `push()` 添加至数组尾部。 |

## `addVitePlugin`

向配置追加 Vite 插件。

::warning
在 Nuxt 5+ 中，使用 `server: false` 或 `client: false` 选项注册的插件将不会调用它们的 `config` 或 `configResolved` 钩子。请改用 `applyToEnvironment()` 方法来实现环境特定插件。
::

### 用法

```ts twoslash
// @errors: 2307
// ---cut---
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
import { svg4VuePlugin } from 'vite-plugin-svg4vue'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-svg-icons',
    configKey: 'nuxtSvgIcons',
  },
  defaults: {
    svg4vue: {
      assetsDirName: 'assets/icons',
    },
  },
  setup (options) {
    addVitePlugin(svg4VuePlugin(options.svg4vue))

    // 或者，只为特定环境添加 vite 插件
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      // ... 您的仅客户端插件的其余内容
    }))
  },
})
```

### 类型

```ts twoslash
// @errors: 2391
import type { Plugin as VitePlugin } from 'vite'
import type { ExtendViteConfigOptions } from '@nuxt/kit'
// ---cut---
function addVitePlugin (pluginOrGetter: VitePlugin | VitePlugin[] | (() => VitePlugin | VitePlugin[]), options?: ExtendViteConfigOptions): void
```

::tip
有关 Vite 插件的更多信息，请参阅 [Vite 官网](https://vite.dev/guide/api-plugin)。您也可以访问 [此仓库](https://github.com/vitejs/awesome-vite#plugins) 查找符合您需求的插件。
::

### 参数

**`pluginOrGetter`**：一个 Vite 插件实例或数组。如果提供的是函数，则该函数必须返回一个 Vite 插件实例或数组。该函数也可以是异步函数或返回 Promise，这对于惰性加载插件非常有用：

```ts twoslash
// @errors: 2307
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    // 惰性加载插件 - 仅在构建实际运行时导入
    addVitePlugin(() => import('my-vite-plugin').then(r => r.default()))
  },
})
```

**`options`**：传递给回调函数的选项对象。该对象可以包含以下属性：

| 属性        | 类型        | 必须      | 描述                                                                            |
| --------- | --------- | ------- | ----------------------------------------------------------------------------- |
| `dev`     | `boolean` | `false` | 如果设置为 `true`，回调函数将在开发模式构建时被调用。                                                |
| `build`   | `boolean` | `false` | 如果设置为 `true`，回调函数将在生产模式构建时被调用。                                                |
| `server`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建服务器包时被调用。**在 Nuxt 5+ 中已弃用。** 请改用 `applyToEnvironment()`。 |
| `client`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建客户端包时被调用。**在 Nuxt 5+ 中已弃用。** 请改用 `applyToEnvironment()`。 |
| `prepend` | `boolean` | `false` | 如果设置为 `true`，回调函数将用 `unshift()` 被添加至数组头部，而非使用 `push()` 添加至数组尾部。               |

## `addWebpackPlugin`

向配置追加 webpack 插件。

### 用法

```ts
import EslintWebpackPlugin from 'eslint-webpack-plugin'
import { addWebpackPlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-eslint',
    configKey: 'eslint',
  },
  defaults: nuxt => ({
    include: [`${nuxt.options.srcDir}/**/*.{js,jsx,ts,tsx,vue}`],
    lintOnStart: true,
  }),
  setup (options, nuxt) {
    const webpackOptions = {
      ...options,
      context: nuxt.options.srcDir,
      files: options.include,
      lintDirtyModulesOnly: !options.lintOnStart,
    }
    addWebpackPlugin(new EslintWebpackPlugin(webpackOptions), { server: false })
  },
})
```

### 类型

```ts twoslash
// @errors: 2391
import type { WebpackPluginInstance } from 'webpack'
import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
// ---cut---
function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[]), options?: ExtendWebpackConfigOptions): void
```

::tip
有关 webpack 插件的更多信息，请参阅 [webpack 官网](https://webpack.js.org/concepts/plugins)。您也可以访问 [此集合](https://webpack.js.org/awesome-webpack/#webpack-plugins) 查找符合您需求的插件。
::

### 参数

**`pluginOrGetter`**：一个 webpack 插件实例或数组。如果提供的是函数，则该函数必须返回一个 webpack 插件实例或数组。该函数也可以是异步函数或返回 Promise，用于惰性加载插件。

**`options`**：传递给回调函数的选项对象。该对象可以包含以下属性：

| 属性        | 类型        | 必须      | 描述                                                              |
| --------- | --------- | ------- | --------------------------------------------------------------- |
| `dev`     | `boolean` | `false` | 如果设置为 `true`，回调函数将在开发模式构建时被调用。                                  |
| `build`   | `boolean` | `false` | 如果设置为 `true`，回调函数将在生产模式构建时被调用。                                  |
| `server`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建服务器包时被调用。                                  |
| `client`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建客户端包时被调用。                                  |
| `prepend` | `boolean` | `false` | 如果设置为 `true`，回调函数将用 `unshift()` 被添加至数组头部，而非使用 `push()` 添加至数组尾部。 |

## `addBuildPlugin`

不依赖于构建器的 `addVitePlugin` 和 `addWebpackPlugin` 版本。如果存在，它将同时向 Vite 和 webpack 配置添加插件。

### 类型

```ts twoslash
// @errors: 2391
import type { ExtendConfigOptions } from '@nuxt/kit'
import type { Plugin as VitePlugin } from 'vite'
import type { WebpackPluginInstance } from 'webpack'
import type { RspackPluginInstance } from '@rspack/core'

interface AddBuildPluginFactory {
  vite?: () => VitePlugin | VitePlugin[]
  webpack?: () => WebpackPluginInstance | WebpackPluginInstance[]
  rspack?: () => RspackPluginInstance | RspackPluginInstance[]
}
// ---cut---
function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void
```

### 参数

**`pluginFactory`**：一个工厂函数，返回一个对象，该对象包含 `vite` 和/或 `webpack` 属性。这些属性必须是返回单个或数组形式的 Vite 插件实例和/或 webpack 插件实例的函数。

**`options`**：传递给回调函数的选项对象。该对象可以包含以下属性：

| 属性        | 类型        | 必须      | 描述                                                              |
| --------- | --------- | ------- | --------------------------------------------------------------- |
| `dev`     | `boolean` | `false` | 如果设置为 `true`，回调函数将在开发模式构建时被调用。                                  |
| `build`   | `boolean` | `false` | 如果设置为 `true`，回调函数将在生产模式构建时被调用。                                  |
| `server`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建服务器包时被调用。                                  |
| `client`  | `boolean` | `false` | 如果设置为 `true`，回调函数将在构建客户端包时被调用。                                  |
| `prepend` | `boolean` | `false` | 如果设置为 `true`，回调函数将用 `unshift()` 被添加至数组头部，而非使用 `push()` 添加至数组尾部。 |

---

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


## Sitemap

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