构建器

源码
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 () {
    // 对所有环境生效的全局配置
    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')
      },
    }))
  },
})
重要提示：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：传递给回调函数的选项对象。此对象可以包含以下属性：

属性类型必需描述
devbooleanfalse若为 true，回调将在开发模式构建时调用。
buildbooleanfalse若为 true，回调将在生产模式构建时调用。
serverbooleanfalse若为 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：传递给回调函数的选项对象。此对象可以包含以下属性：

属性类型必需描述
devbooleanfalse若为 true，回调将在开发模式构建时调用。
buildbooleanfalse若为 true，回调将在生产模式构建时调用。
serverbooleanfalse若为 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))

    // 或者，只对某个环境添加 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：传递给回调函数的选项对象。此对象可以包含以下属性：

属性类型必需描述
devbooleanfalse若为 true，回调将在开发模式构建时调用。
buildbooleanfalse若为 true，回调将在生产模式构建时调用。
serverbooleanfalse若为 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：传递给回调函数的选项对象。此对象可以包含以下属性：

属性类型必需描述
devbooleanfalse若为 true，回调将在开发模式构建时调用。
buildbooleanfalse若为 true，回调将在生产模式构建时调用。
serverbooleanfalse若为 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 插件实例或 Vite 插件实例数组和/或 返回 webpack 插件实例或 webpack 插件实例数组的函数。

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

PropertyTypeRequiredDescription
devbooleanfalseIf set to true, the callback function will be called when building in development mode.
buildbooleanfalseIf set to true, the callback function will be called when building in production mode.
serverbooleanfalseIf set to true, the callback function will be called when building the server bundle.
clientbooleanfalseIf set to true, the callback function will be called when building the client bundle.
prependbooleanfalseIf set to true, the callback function will be prepended to the array with unshift() instead of push().

setBuildOutput

Set a build output provider for the given key. Build outputs are the contract between builders (Vite, webpack, Rspack, or a custom builder) and the Nitro server runtime: each key maps to a nuxt/* subpath import the server runtime resolves at build time. This is typically called from inside a builder, or from a module that participates in the build.

Learn how the build output contract works.

Type

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

Parameters

key: The build output key. One of serverEntry, clientManifest, clientPrecomputed, ssrStyles, entryChunkName or entryIds.

provider: The value for that key: a (possibly async) function returning the module body as a string, read lazily when the server build resolves the corresponding nuxt/* import.

Example

import { setBuildOutput } from '@nuxt/kit'

// Re-export the built SSR entry by absolute specifier.
setBuildOutput('serverEntry', () => `export { default } from ${JSON.stringify(serverEntryURL)}`)

// Provide the serialized client manifest.
setBuildOutput('clientManifest', () => `export default ${serializedManifest}`)

// Re-export the emitted per-component styles map for `nuxt/styles`.
setBuildOutput('ssrStyles', () => `export { default } from ${JSON.stringify(pathToFileURL(resolve(serverDir, 'styles.mjs')).href)}`)