---
title: "构建器"
description: "Nuxt Kit 提供了一组实用工具，帮助你使用构建器。这些函数允许你扩展 Vite 和 webpack 的配置。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.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
此钩子现已弃用，我们建议使用 Vite 插件中的 `config` 钩子，或者针对特定环境配置的 `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.zhcndoc.com/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+ 中已弃用。** 请改用 `addVitePlugin()` 和 `applyToEnvironment()`。 |
| `client`  | `boolean` | `false` | 若为 `true`，回调将在构建客户端包时调用。**在 Nuxt 5+ 中已弃用。** 请改用 `addVitePlugin()` 和 `applyToEnvironment()`。 |
| `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.zhcndoc.com/guide/api-plugin)。你也可以使用 [此仓库](https://github.com/vitejs/awesome-vite#plugins) 来查找适合你需求的插件。
::

### 参数

**`pluginOrGetter`**：一个 Vite 插件实例或 Vite 插件实例数组。如果提供一个函数，则该函数必须返回一个 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 插件实例数组。如果提供一个函数，则该函数必须返回一个 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 插件实例或 Vite 插件实例数组和/或 返回 webpack 插件实例或 webpack 插件实例数组的函数。

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

| 属性        | 类型        | 必需      | 描述                                                             |
| --------- | --------- | ------- | -------------------------------------------------------------- |
| `dev`     | `boolean` | `false` | 若设置为 `true`，回调函数将在开发模式构建时调用。                                   |
| `build`   | `boolean` | `false` | 若设置为 `true`，回调函数将在生产模式构建时调用。                                   |
| `server`  | `boolean` | `false` | 若设置为 `true`，回调函数将在构建服务端包时调用。                                   |
| `client`  | `boolean` | `false` | 若设置为 `true`，回调函数将在构建客户端包时调用。                                   |
| `prepend` | `boolean` | `false` | 若设置为 `true`，回调函数将通过 `unshift()` 添加到数组前端，而非使用 `push()` 添加到数组末端。 |

## `setBuildOutput`

为给定键设置构建输出提供程序。构建输出是构建器（Vite、webpack、Rspack 或自定义构建器）与 Nitro 服务器运行时之间的契约：每个键都映射到一个 `nuxt/*` 子路径导入，服务器运行时会在构建时解析该导入。这通常在构建器内部，或参与构建的模块中调用。

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/builders#the-build-output-contract"}
了解构建输出契约的工作方式。
::

### 类型

```ts twoslash
// @errors: 2391
import type { NuxtBuildOutputs } from '@nuxt/schema'
// ---cut---
function setBuildOutput<K extends keyof NuxtBuildOutputs> (key: K, provider: NuxtBuildOutputs[K]): void
```

### 参数

**`key`**：构建输出键。可以是 `serverEntry`、`clientManifest`、`clientPrecomputed`、`ssrStyles`、`entryChunkName` 或 `entryIds` 之一。

**`provider`**：该键对应的值：一个（可能是异步的）函数，返回模块正文字符串；当服务器构建解析对应的 `nuxt/*` 导入时，会延迟读取该字符串。

### 示例

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

// 通过绝对说明符重新导出已构建的 SSR 入口。
setBuildOutput('serverEntry', () => `export { default } from ${JSON.stringify(serverEntryURL)}`)

// 提供序列化后的客户端清单。
setBuildOutput('clientManifest', () => `export default ${serializedManifest}`)

// 重新导出为 `nuxt/styles` 生成的逐组件样式映射。
setBuildOutput('ssrStyles', () => `export { default } from ${JSON.stringify(pathToFileURL(resolve(serverDir, 'styles.mjs')).href)}`)
```

---

- [源码](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.