构建器

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

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

extendViteConfig

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

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

Usage

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')
      },
    }))
  },
})
Important: The config hook runs before applyToEnvironment and modifies the global configuration. Use configEnvironment for environment-specific configuration changes.

Type

function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
请查看 Vite 网站以获取更多关于其配置的信息。

Parameters

callback：一个回调函数，将会使用 Vite 配置对象调用。

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

PropertyTypeRequiredDescription
devbooleanfalse如果设为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设为 true，回调函数将在生产模式构建时被调用。
serverbooleanfalse如果设为 true，回调函数将在构建服务端包时被调用。在 Nuxt 5+ 中已弃用。 请改用 addVitePlugin() 和 applyToEnvironment()。
clientbooleanfalse如果设为 true，回调函数将在构建客户端包时被调用。在 Nuxt 5+ 中已弃用。 请改用 addVitePlugin() 和 applyToEnvironment()。
prependbooleanfalse如果设为 true，回调函数将使用 unshift() 被添加到数组前端，而不是使用 push() 添加到数组末端。

extendWebpackConfig

扩展 webpack 配置。回调函数可能会被多次调用，应用到客户端和服务端构建时都会触发。

Usage

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

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

Type

function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
请查看 webpack 网站以获取更多关于其配置的信息。

Parameters

callback：一个回调函数，将会使用 webpack 配置对象调用。

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

PropertyTypeRequiredDescription
devbooleanfalse如果设为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设为 true，回调函数将在生产模式构建时被调用。
serverbooleanfalse如果设为 true，回调函数将在构建服务端包时被调用。
clientbooleanfalse如果设为 true，回调函数将在构建客户端包时被调用。
prependbooleanfalse如果设为 true，回调函数将使用 unshift() 被添加到数组前端，而不是使用 push() 添加到数组末端。

addVitePlugin

向配置追加 Vite 插件。

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

Usage

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

Type

function addVitePlugin (pluginOrGetter: VitePlugin | VitePlugin[] | (() => VitePlugin | VitePlugin[]), options?: ExtendViteConfigOptions): void
有关 Vite 插件的更多信息，请参见 Vite 官方文档。你也可以使用 此仓库 来查找适合你需求的插件。

Parameters

pluginOrGetter：一个 Vite 插件实例或 Vite 插件实例数组。如果提供一个函数，则该函数必须返回一个 Vite 插件实例或 Vite 插件实例数组。

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

PropertyTypeRequiredDescription
devbooleanfalse如果设为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设为 true，回调函数将在生产模式构建时被调用。
serverbooleanfalse如果设为 true，回调函数将在构建服务端包时被调用。 在 Nuxt 5+ 中已弃用。 请改用 applyToEnvironment()。
clientbooleanfalse如果设为 true，回调函数将在构建客户端包时被调用。 在 Nuxt 5+ 中已弃用。 请改用 applyToEnvironment()。
prependbooleanfalse如果设为 true，回调函数将使用 unshift() 被添加到数组前端，而不是使用 push() 添加到数组末端。

addWebpackPlugin

向配置追加 webpack 插件。

Usage

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

Type

function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[]), options?: ExtendWebpackConfigOptions): void
有关 webpack 插件的更多信息，请参见 webpack 官方文档。你也可以使用 此集合 来查找适合你需求的插件。

Parameters

pluginOrGetter：一个 webpack 插件实例或 webpack 插件实例数组。如果提供一个函数，则该函数必须返回一个 webpack 插件实例或 webpack 插件实例数组。

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

PropertyTypeRequiredDescription
devbooleanfalse如果设为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设为 true，回调函数将在生产模式构建时被调用。
serverbooleanfalse如果设为 true，回调函数将在构建服务端包时被调用。
clientbooleanfalse如果设为 true，回调函数将在构建客户端包时被调用。
prependbooleanfalse如果设为 true，回调函数将使用 unshift() 被添加到数组前端，而不是使用 push() 添加到数组末端。

addBuildPlugin

与 addVitePlugin 和 addWebpackPlugin 无关构建器的版本。若存在相应构建器，则会将插件同时添加到 Vite 和 webpack 配置中。

Type

function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void

Parameters

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

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

PropertyTypeRequiredDescription
devbooleanfalse如果设为 true，回调函数将在开发模式构建时被调用。
buildbooleanfalse如果设为 true，回调函数将在生产模式构建时被调用。
serverbooleanfalse如果设为 true，回调函数将在构建服务端包时被调用。
clientbooleanfalse如果设为 true，回调函数将在构建客户端包时被调用。
prependbooleanfalse如果设为 true，回调函数将使用 unshift() 被添加到数组前端，而不是使用 push() 添加到数组末端。