构建器

源文件
Nuxt Kit 提供了一套工具函数来帮助您使用构建器。这些函数允许您扩展 Vite 和 webpack 的配置。

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

extendViteConfig

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

此钩子现已弃用，我们建议改用 Vite 插件并配合 config 钩子，或者对于环境特定的配置，使用 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 () {
    // For global configuration (affects all environments)
    addVitePlugin(() => ({
      name: 'my-global-plugin',
      config (config) {
        // This runs before environment setup
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('cross-fetch')
      },
    }))

    // For environment-specific configuration
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      configEnvironment (name, config) {
        // This only affects the client environment
        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：传递给回调函数的选项。该对象可以包含以下属性

属性类型必需描述
开发booleanfalse如果设置为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设置为 true，回调函数将在生产模式构建时被调用。
服务器booleanfalse如果设置为 true，回调函数将在构建服务器包时被调用。在 Nuxt 5+ 中已弃用。请改用 addVitePlugin() 配合 applyToEnvironment()。
clientbooleanfalse如果设置为 true，回调函数将在构建客户端包时被调用。在 Nuxt 5+ 中已弃用。请改用 addVitePlugin() 配合 applyToEnvironment()。
prependbooleanfalse如果设置为 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：传递给回调函数的选项。该对象可以包含以下属性

属性类型必需描述
开发booleanfalse如果设置为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设置为 true，回调函数将在生产模式构建时被调用。
服务器booleanfalse如果设置为 true，回调函数将在构建服务器包时被调用。
clientbooleanfalse如果设置为 true，回调函数将在构建客户端包时被调用。
prependbooleanfalse如果设置为 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))

    // or, to add a vite plugin to only one environment
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      // ... rest of your client-only plugin
    }))
  },
})

类型

// @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 () {
    // Lazy load the plugin - only imported when the build actually runs
    addVitePlugin(() => import('my-vite-plugin').then(r => r.default()))
  },
})

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

属性类型必需描述
开发booleanfalse如果设置为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设置为 true，回调函数将在生产模式构建时被调用。
服务器booleanfalse如果设置为 true，回调函数将在构建服务器包时被调用。在 Nuxt 5+ 中已弃用。请改用 applyToEnvironment()。
clientbooleanfalse如果设置为 true，回调函数将在构建客户端包时被调用。在 Nuxt 5+ 中已弃用。请改用 applyToEnvironment()。
prependbooleanfalse如果设置为 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：传递给回调函数的选项。该对象可以包含以下属性

属性类型必需描述
开发booleanfalse如果设置为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设置为 true，回调函数将在生产模式构建时被调用。
服务器booleanfalse如果设置为 true，回调函数将在构建服务器包时被调用。
clientbooleanfalse如果设置为 true，回调函数将在构建客户端包时被调用。
prependbooleanfalse如果设置为 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 插件实例（或数组）和/或 webpack 插件实例（或数组）的函数。

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

属性类型必需描述
开发booleanfalse如果设置为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设置为 true，回调函数将在生产模式构建时被调用。
服务器booleanfalse如果设置为 true，回调函数将在构建服务器包时被调用。
clientbooleanfalse如果设置为 true，回调函数将在构建客户端包时被调用。
prependbooleanfalse如果设置为 true，回调函数将使用 unshift() 而不是 push() 添加到数组头部。