API: 构建配置

构建配置

Nuxt.js 允许你根据服务端需求,自定义 webpack 的构建配置。

analyze

Nuxt.js 使用 webpack-bundle-analyzer 分析并可视化构建后的打包文件,你可以基于分析结果来决定如何优化它。

  • 类型: BooleanObject
  • 默认值: false

如果是 Object 类型, 可以移步 这里 查看可用的属性。

例如 (nuxt.config.js):

module.exports = {
  build: {
    analyze: true
    // or
    analyze: {
      analyzerMode: 'static'
    }
  }
}

提示: 可通过 nuxt build --analyzenuxt build -a 命令来启用该分析器进行编译构建,分析结果可在 http://localhost:8888 上查看。

babel

为 JS 和 Vue 文件设定自定义的 babel 配置。

  • 类型: Object
  • 默认:
{
  babelrc: false,
  cacheDirectory: undefined,
  presets: ['@nuxt/babel-preset-app']
}

默认为 @nuxt/babel-preset-appclient构建中是ie:'9',在server构建中是node:'current'

注意: build.babel.presets 中配置的预设将应用于客户端和服务器构建。目标将由Nuxt相应地设置(客户端/服务器)。如果要为客户端或服务器版本配置不同的预设,请使用presets作为函数:

export default {
  build: {
    babel: {
      presets ({ isServer }) {
        const targets = isServer ? { node: '10' } : { ie: '11' }
        return [
          [ require.resolve('@nuxt/babel-preset-app'), { targets } ]
        ]
      }
    }
  }
}

我们强烈建议使用默认预设。但是,如果必须,您可以更改预设。

Example for custom presets:

export default {
  build: {
    babel: {
      presets: ['es2015', 'stage-0']
    }
  }
}

cache

  • 类型: Boolean
  • 默认: false
  • ⚠️ 实验性的

启用缓存 terser-webpack-plugincache-loader

crossorigin

  • 类型: String
  • 默认: undefined

在生成的HTML中的 <link rel="stylesheet"><script> 标记上配置 crossorigin 属性。 请查看 CORS settings attributes 了解更多可用选项。

cssSourceMap

  • 类型: boolean
  • 默认: true 为开发模式(development), false 为生产模式(production)。

开启 CSS Source Map 支持

devMiddleware

  • 类型: Object

请查看 webpack-dev-middleware 了解更多可用选项。

devtools

  • 类型: boolean
  • 默认: false

配置是否允许 vue-devtools 调试。

如果您已经通过 nuxt.config.js 或其他方式激活,则无论标志为 true 或 false,devtools都会启用。

extend

  • 类型: Function

为客户端和服务端的构建配置进行手工的扩展处理。

该扩展方法会被调用两次,一次在服务端打包构建的时候,另外一次是在客户端打包构建的时候。该方法的参数如下:

  1. Webpack 配置对象
  2. 构建环境对象,包括这些属性(全部为布尔类型):isDevisClientisServer

警告: 提供的isClientisServer键与context中可用的键分开, 它们是长期支持的。这里不要使用process.clientprocess.server,因为它们是'undefined'

例如 (nuxt.config.js):

module.exports = {
  build: {
    extend (config, { isClient }) {
      // 为 客户端打包 进行扩展配置
      if (isClient) {
        config.devtool = 'eval-source-map'
      }
    }
  }
}

如果你想了解更多关于webpack的配置,可以移步 Nuxt.js 源码的 webpack 目录

loaders in extend

loaders具有与之相同的对象结构 build.loaders, 所以你可以在extend中更改loaders的选项。

例如 (nuxt.config.js):

export default {
  build: {
    extend (config, { isClient, loaders: { vue } }) {
      // 仅扩展客户端中的webpack配置
      if (isClient) {
        vue.transformAssetUrls.video = ['src', 'poster']
      }
    }
  }
}

extractCSS

使用Vue 服务器端渲染指南启用常见CSS提取。

  • 类型: Boolean
  • 默认: false

使用extract-css-chunks-webpack-plugin将主块中的 CSS 提取到一个单独的 CSS 文件中(自动注入模板),该文件允许单独缓存文件。当有很多共用 CSS 时建议使用此方法,异步组件中的 CSS 将保持内联为JavaScript字符串并由vue-style-loader处理。

filenames

  • 类型: Object

自定义打包文件名

默认值:

{
  app: ({ isDev }) => isDev ? '[name].js' : '[chunkhash].js',
  chunk: ({ isDev }) => isDev ? '[name].js' : '[chunkhash].js',
  css: ({ isDev }) => isDev ? '[name].css' : '[contenthash].css',
  img: ({ isDev }) => isDev ? '[path][name].[ext]' : 'img/[hash:7].[ext]',
  font: ({ isDev }) => isDev ? '[path][name].[ext]' : 'fonts/[hash:7].[ext]',
  video: ({ isDev }) => isDev ? '[path][name].[ext]' : 'videos/[hash:7].[ext]'
}

此示例将 chunk 名称更改为数字id (nuxt.config.js):

export default {
  build: {
    filenames: {
      chunk: ({ isDev }) => isDev ? '[name].js' : '[id].[chunkhash].js'
    }
  }
}

要更多了解使用,可以移步webpack documentation

friendlyErrors

  • 类型: Boolean
  • 默认: true (启用叠加)

友好的错误 Webpack 插件

hardSource

  • 类型: Boolean
  • 默认: false
  • ⚠️ 实验性的

开启 HardSourceWebpackPlugin

hotMiddleware

  • 类型: Object

请查看 webpack-hot-middleware 了解更多可用选项。

html.minify

  • 类型: Object
  • 默认:
{
  collapseBooleanAttributes: true,
  collapseWhitespace: false,
  decodeEntities: true,
  minifyCSS: true,
  minifyJS: true,
  processConditionalComments: true,
  removeAttributeQuotes: false,
  removeComments: false,
  removeEmptyAttributes: true,
  removeOptionalTags: false,
  removeRedundantAttributes: true,
  removeScriptTypeAttributes: false,
  removeStyleLinkTypeAttributes: false,
  removeTagWhitespace: false,
  sortClassName: false,
  trimCustomFragments: true,
  useShortDoctype: true
}

用于压缩在构建打包过程中创建的HTML文件配置html-minifier的插件(将应用于所有模式)。

loaders

  • 类型: Object

自定义 webpack 加载器

  • Default:
{
  file: {},
  fontUrl: { limit: 1000 },
  imgUrl: { limit: 1000 },
  pugPlain: {},
  vue: {
    transformAssetUrls: {
      video: 'src',
      source: 'src',
      object: 'src',
      embed: 'src'
    }
  },
  css: {},
  cssModules: {
    localIdentName: '[local]_[hash:base64:5]'
  },
  less: {},
  sass: {
    indentedSyntax: true
  },
  scss: {},
  stylus: {},
  vueStyle: {}
}

注意:除了在nuxt.config.js中指定配置外,它还可以通过build.extend修改。

loaders.file

更多详情查看 file-loader 配置.

loaders.fontUrl and loaders.imgUrl

更多详情查看 url-loader 配置.

loaders.pugPlain

更多详情查看 pug-plain-loaderPug compiler 配置.

loaders.vue

更多详情查看 vue-loader 配置.

loaders.css and loaders.cssModules

更多详情查看 css-loader 配置. 注意:cssModules是使用的loader选项 CSS Modules

loaders.less

您可以通过loaders.less将任何Less特定选项传递给less-loader。 请查看 Less 文档 来获取更多配置信息。

loaders.sass and loaders.scss

查看 Node Sass 文档 来获取更多配置信息。 Note: loaders.sass is for Sass Indented Syntax

注意:loaders.sass用于Sass 缩进

loaders.vueStyle

更多配置信息查看 vue-style-loader 配置

optimization

  • 类型: Object

  • 默认:

    {
      minimize: true,
      minimizer: [
        // terser-webpack-plugin
        // optimize-css-assets-webpack-plugin
      ],
      splitChunks: {
        chunks: 'all',
        automaticNameDelimiter: '.',
        name: undefined,
        cacheGroups: {}
      }
    }

开发分析模式下,splitChunks.name的默认值为true。 You can set minimizer to a customized Array of plugins or set minimize to false to disable all minimizers. 您可以将minimizer设置为自定义插件,或将minim设置为false以禁用所有minimize。(默认在开发环境情况下,minimize被禁用)。

查看 Webpack Optimization来了解更多配置信息。

terser

  • 类型: ObjectBoolean
  • 默认:
{
  parallel: true,
  cache: false,
  sourceMap: false,
  extractComments: {
    filename: 'LICENSES'
  },
  terserOptions: {
    output: {
      comments: /^\**!|@preserve|@license|@cc_on/
    }
  }
}

设置为false可以禁用此插件。

当webpack中 config.devtoolsource-?map匹配时,将启用sourceMap

查看 webpack-contrib/terser-webpack-plugin来了解更多配置信息。

optimizeCSS

  • 类型: ObjectBoolean
  • 默认:
    • false
    • {} when extractCSS is enabled

OptimizeCSSAssets 插件配置查看NMFR/optimize-css-assets-webpack-plugin.

parallel

  • 类型: Boolean
  • 默认: false

在webpack构建打包中开启 thread-loader

plugins

  • 类型: Array
  • 默认值: []

配置 Webpack 插件

例如 (nuxt.config.js):

import webpack from 'webpack'
import { version } from './package.json'
export default {
  build: {
    plugins: [
      new webpack.DefinePlugin({
        'process.VERSION': version
      })
    ]
  }
}

postcss

  • 类型: Array, Object(推荐), FunctionBoolean

注意:Nuxt.js已应用PostCSS Preset Env。默认情况下,它将启用Stage 2功能和Autoprefixer,你可以使用build.postcss.preset来配置它。

自定义 postcss 配置

默认值:

{
  plugins: {
    'postcss-import': {},
    'postcss-url': {},
    'postcss-preset-env': {},
    'cssnano': { preset: 'default' } // disabled in dev mode
  }
}

例如 (nuxt.config.js):

export default {
  build: {
    postcss: {
      plugins: {
        // Disable `postcss-url`
        'postcss-url': false,
        // Add some plugins
        'postcss-nested': {},
        'postcss-responsive-type': {},
        'postcss-hexrgba': {}
      },
      preset: {
        autoprefixer: {
          grid: true
        }
      }
    }
  }
}

profile

  • 类型: Boolean
  • 默认: 开启只需在命令行中加入: --profile

开启 profiler 请查看 WebpackBar

publicPath

Nuxt.js允许您将dist文件上传到CDN来获得最快渲染性能,只需将publicPath设置为CDN即可。

  • 类型: String
  • 默认: '/_nuxt/'

例如 (nuxt.config.js):

export default {
  build: {
    publicPath: 'https://cdn.nuxtjs.org'
  }
}

然后,当启动nuxt build时, 将.nuxt/dist/client目录的内容上传到您的CDN即可!

quiet

控制部分构建信息输出日志

  • 类型: Boolean
  • 默认: 检测到CItest环境时启用 std-env

splitChunks

  • 类型: Object

  • 默认:

    {
      layouts: false,
      pages: true,
      commons: true
    }

如果代码分模块用于 layout, pagescommons (常用: vue|vue-loader|vue-router|vuex...).

ssr

为服务器端渲染创建特殊的webpack包。

  • 类型: Boolean
  • 默认: true 为通用模式,falsespa模式

如果未提供,则根据默认模式自动设置此选项。

styleResources

  • 类型: Object
  • 默认: {}

当您需要在页面中注入一些变量和mixin而不必每次都导入它们时,这非常有用。

Nuxt.js 使用 https://github.com/nuxt-community/style-resources-module 来实现这种行为。

您需要为css预处理器指定要包含的 模式 / 路径 : less, sass, scssstylus

您不能在此处使用路径别名(~@),

:warning: You cannot use path aliases here (~ and @),你需要使用相对或绝对路径。

安装 style-resources:

$ yarn add @nuxtjs/style-resources

根据需要安装:

  • SASS: $ yarn add sass-loader node-sass
  • LESS: $ yarn add less-loader less
  • Stylus: $ yarn add stylus-loader stylus

修改 nuxt.config.js:

export default {
  modules: [
    '@nuxtjs/style-resources'
  ],
  styleResources: {
    scss: './assets/variables.scss',
    less: './assets/**/*.less'
    // sass: ...
  }
}

然后就可以随处直接使用定义过的变量或函数。

templates

Nuxt.js允许您自定义自己的模板,这些模板将基于Nuxt配置进行渲染。 此功能特别适用于使用 modules

  • 类型: Array

Example (nuxt.config.js):

export default {
  build: {
    templates: [
      {
        src: '~/modules/support/plugin.js', // `src` 可以是绝对的或相对的路径
        dst: 'support.js', // `dst` 是相对于项目`.nuxt`目录
        options: { // 选项`options`选项可以将参数提供给模板
          live_chat: false
        }
      }
    ]
  }
}

使用lodash.template呈现模板,您可以了解有关使用它们的更多信息here

transpile

  • 类型: Array<string | RegExp>
  • 默认: []

如果要使用Babel与特定的依赖关系进行转换,你可以在build.transpile中添加它们,transpile中的选项可以是字符串正则表达式对象,用于匹配依赖项文件名。

vueLoader

注意:此配置在Nuxt 2.0+中已被删除,请使用 build.loaders.vue 来替代

  • 类型: Object

  • 默认:

    {
      productionMode: !this.options.dev,
      transformAssetUrls: {
        video: 'src',
        source: 'src',
        object: 'src',
        embed: 'src'
      }
    }

指定 Vue Loader 配置.

vendor

注意:在Nuxt.js 2.0+版本中,vendor由于Webpack 4,将废弃该API但保留使用方法作为兼容低版本处理。查看:Nuxt.js 2.0 更新文档

Nuxt.js 允许你在自动生成的 vendor.bundle.js 文件中添加一些模块,以减少应用 bundle 的体积。这里说的是一些你所依赖的第三方模块 (比如 axios)

  • 类型: Array
    • 数组元素类型: String

想要把模块打包进 vendor bundle,你可以在 nuxt.config.jsbuild.vendor 字段中配置:

module.exports = {
  build: {
    vendor: ['axios']
  }
}

你也可以配置文件路径,比如一些自己写的库:

module.exports = {
  build: {
    vendor: [
      'axios',
      '~plugins/my-lib.js'
    ]
  }
}

watch

您可以使用watch来监听文件更改。此功能特别适用用在modules中。

  • 类型: Array<String>
export default {
  build: {
    watch: [
      '~/.nuxt/support.js'
    ]
  }
}

By default, the build process does not scan files inside symlinks. This boolean includes them, thus allowing usage of symlinks inside folders such as the "pages" folder, for example.

  • Type: Boolean
export default {
  build: {
    followSymlinks: false
  }
}

Platinum Sponsors

Storyblok
Support Us