Builder

Nuxt Kit 提供了一系列工具，帮助你使用构建器。这些函数允许你扩展 Vite 和 webpack 配置。

Nuxt 有基于 Vite 和 webpack 的构建器。你可以使用 extendViteConfig 和 extendWebpackConfig 函数扩展传给每个构建器的配置。你也可以通过 addVitePlugin、addWebpackPlugin 和 addBuildPlugin 添加额外的插件。

`extendViteConfig`

扩展 Vite 配置。回调函数在应用于客户端和服务端构建时可能会被多次调用。

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

用法

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()：

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

export default defineNuxtModule({
  setup () {
    // 全局配置（影响所有环境）
    addVitePlugin(() => ({
      name: 'my-global-plugin',
      config (config) {
        // 这在环境 setup 之前运行
        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) {
        // 这只影响 client 环境
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('client-only-package')
      },
    }))
  },
})

重要： config 钩子在 applyToEnvironment 之前运行并修改全局配置。请使用 configEnvironment 进行特定环境的配置更改。 :

类型

// @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

访问 Vite 官网以获取更多关于其配置的信息。 :

参数

callback：一个会接收 Vite 配置对象作为参数的回调函数。

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

属性	类型	必填	描述
`dev`	`boolean`	`false`	如果设为 `true`，回调函数会在开发模式构建时被调用。
`build`	`boolean`	`false`	如果设为 `true`，回调函数会在生产模式构建时被调用。
`server`	`boolean`	`false`	如果设为 `true`，回调函数会在构建服务端 bundle 时被调用。在 Nuxt 5+ 中已弃用。请改用 `addVitePlugin()` 配合 `applyToEnvironment()`。
`client`	`boolean`	`false`	如果设为 `true`，回调函数会在构建客户端 bundle 时被调用。在 Nuxt 5+ 中已弃用。请改用 `addVitePlugin()` 配合 `applyToEnvironment()`。
`prepend`	`boolean`	`false`	如果设为 `true`，回调函数会用 `unshift()` 而非 `push()` 加到数组开头。

`extendWebpackConfig`

扩展 webpack 配置。回调函数在应用于客户端和服务端构建时可能会被多次调用。

用法

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

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

类型

// @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

访问 webpack 官网以获取更多关于其配置的信息。 :

参数

callback：一个会接收 webpack 配置对象作为参数的回调函数。

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

属性	类型	必填	描述
`dev`	`boolean`	`false`	如果设为 `true`，回调函数会在开发模式构建时被调用。
`build`	`boolean`	`false`	如果设为 `true`，回调函数会在生产模式构建时被调用。
`server`	`boolean`	`false`	如果设为 `true`，回调函数会在构建服务端 bundle 时被调用。
`client`	`boolean`	`false`	如果设为 `true`，回调函数会在构建客户端 bundle 时被调用。
`prepend`	`boolean`	`false`	如果设为 `true`，回调函数会用 `unshift()` 而非 `push()` 加到数组开头。

`addVitePlugin`

向配置中追加 Vite 插件。

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

用法

// @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'
      },
      // ... 其余的客户端专属插件
    }))
  },
})

类型

// @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

访问 Vite 官网以获取更多关于 Vite 插件的信息。你也可以使用这个仓库来寻找适合你需求的插件。 :

参数

pluginOrGetter：一个 Vite 插件实例或一组 Vite 插件实例。如果提供的是函数，它必须返回一个 Vite 插件实例或一组 Vite 插件实例。该函数也可以是异步的或返回一个 Promise，这对于懒加载插件很有用：

// @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`，回调函数会在构建服务端 bundle 时被调用。在 Nuxt 5+ 中已弃用。请改用 `applyToEnvironment()`。
`client`	`boolean`	`false`	如果设为 `true`，回调函数会在构建客户端 bundle 时被调用。在 Nuxt 5+ 中已弃用。请改用 `applyToEnvironment()`。
`prepend`	`boolean`	`false`	如果设为 `true`，回调函数会用 `unshift()` 而非 `push()` 加到数组开头。

`addWebpackPlugin`

向配置中追加 webpack 插件。

用法

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 })
  },
})

类型

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

访问 webpack 官网以获取更多关于 webpack 插件的信息。你也可以使用这个集合来寻找适合你需求的插件。 :

参数

pluginOrGetter：一个 webpack 插件实例或一组 webpack 插件实例。如果提供的是函数，它必须返回一个 webpack 插件实例或一组 webpack 插件实例。该函数也可以是异步的或返回一个 Promise，从而实现插件的懒加载。

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

属性	类型	必填	描述
`dev`	`boolean`	`false`	如果设为 `true`，回调函数会在开发模式构建时被调用。
`build`	`boolean`	`false`	如果设为 `true`，回调函数会在生产模式构建时被调用。
`server`	`boolean`	`false`	如果设为 `true`，回调函数会在构建服务端 bundle 时被调用。
`client`	`boolean`	`false`	如果设为 `true`，回调函数会在构建客户端 bundle 时被调用。
`prepend`	`boolean`	`false`	如果设为 `true`，回调函数会用 `unshift()` 而非 `push()` 加到数组开头。

`addBuildPlugin`

addVitePlugin 和 addWebpackPlugin 与构建器无关的版本。如果 Vite 和 webpack 配置都存在，它会将插件添加到两者。

类型

// @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`，回调函数会在构建服务端 bundle 时被调用。
`client`	`boolean`	`false`	如果设为 `true`，回调函数会在构建客户端 bundle 时被调用。
`prepend`	`boolean`	`false`	如果设为 `true`，回调函数会用 `unshift()` 而非 `push()` 加到数组开头。

`setBuildOutput`

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

了解构建输出契约是如何工作的。 :

类型

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

参数

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

provider：该 key 对应的值：一个（可能是异步的）函数，以字符串形式返回模块主体，当服务端构建解析对应的 nuxt/* 导入时会被惰性读取。

示例

import { setBuildOutput } from '@nuxt/kit'

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

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

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