本页导读：

配置

Nuxt 的默认配置已覆盖大多数使用场景。可以使用 nuxt.config.js 覆盖这些默认配置。

css 属性

可以配置全局应用（在所有页面中）的 CSS 文件/模块/库。

如果想使用 sass，请安装 node-sass 和 sass-loader 包。

在 nuxt.config.js 中添加 CSS 资源：

nuxt.config.js

export default {
  css: [
    // 直接加载 Node.js 模块（此处为 Sass 文件）
    'bulma',
    // 项目内的 CSS 文件
    '~/assets/css/main.css',
    // 项目内的 SCSS 文件
    '~/assets/css/main.scss'
  ]
}

Nuxt 会自动从扩展名推断文件类型并使用 Webpack 的适当预处理器加载器。如果需要使用这些加载器，请自行安装所需的加载器。

样式扩展名

在 nuxt 配置文件的 css 属性数组中，CSS/SCSS/Postcss/Less/Stylus/ 等文件的扩展名可以省略。

nuxt.config.js

export default {
  css: ['~/assets/css/main', '~/assets/css/animations']
}

如果存在两个同名文件，例如 main.scss 和 main.css，且在 css 数组中未明确指定扩展名（如 css: ['~/assets/css/main']），则只会根据 styleExtensions 的顺序加载其中一个文件。在这种情况下，由于 css 在默认 styleExtension 数组中排在首位，只会加载 css 文件，scss 文件会被忽略。

默认顺序：['css', 'pcss', 'postcss', 'styl', 'stylus', 'scss', 'sass', 'less']

预处理器

得益于 Vue Loader ，只需使用 lang 属性即可在 <template> 或 <style> 等中使用各种预处理器。

使用 Pug 和 Sass 的 pages/index.vue 示例：

pages/index.vue

<template lang="pug">
  h1.red Hello {{ name }}!
</template>

<style lang="scss">
  .red {
    color: red;
  }
</style>

需要安装 Webpack 加载器才能使用这些预处理器：

Yarn

yarn add --dev pug pug-plain-loader
yarn add --dev sass sass-loader@10

NPM

npm install --save-dev pug pug-plain-loader
npm install --save-dev sass sass-loader@10

外部资源

全局配置

可以在 head 对象或函数中包含外部资源。如 head API 文档所述，以下示例展示了以对象或函数形式使用 head 的方式。如果想使用 Vue 组件的值（如计算属性或数据），可以使用 head() 函数返回最终的 head 对象。还可以向每个资源传递可选的 body: true，将资源包含在关闭的 </body> 标签之前。

在 nuxt.config.js 中包含资源（此处为 head 对象）：

export default {
  head: {
    script: [
      {
        src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js'
      }
    ],
    link: [
      {
        rel: 'stylesheet',
        href: 'https://fonts.googleapis.com/css?family=Roboto&display=swap'
      }
    ]
  }
}

局部配置

在 pages/ 目录（此处为 head 函数）内的 .vue 文件中包含资源：

<template>
  <h1>About page with jQuery and Roboto font</h1>
</template>

<script>
  export default {
    head() {
      return {
        script: [
          {
            src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js'
          }
        ],
        link: [
          {
            rel: 'stylesheet',
            href: 'https://fonts.googleapis.com/css?family=Roboto&display=swap'
          }
        ]
      }
    }
  }
</script>

<style scoped>
  h1 {
    font-family: Roboto, sans-serif;
  }
</style>

PostCSS 插件

如果项目目录中存在 postcss.config.js，请将其重命名或删除，然后在 nuxt.config.js 文件中添加以下内容：

export default {
  build: {
    postcss: {
      // 以插件名为键，参数为值添加插件
      // 请提前使用 npm 或 yarn 将这些依赖安装好
      plugins: {
        // 传入 false 值以禁用插件
        'postcss-url': false,
        'postcss-nested': {},
        'postcss-responsive-type': {},
        'postcss-hexrgba': {}
      },
      preset: {
        // 传入 false 值以禁用插件
        autoprefixer: {
          grid: true
        }
      }
    }
  }
}

JSX

Nuxt 使用基于 babel 默认配置的官方 @vue/babel-preset-app 的 @nuxt/babel-preset-app ，因此可以在组件中使用 JSX。

可以在组件的 render 方法中使用 JSX：

export default {
  data () {
    return { name: 'World' }
  },
  render (h) {
    return <h1 class="red">{this.name}</h1>
  }
}

将 createElement 别名为 h 是 Vue 生态系统中常见的惯例。但对于 JSX 来说这是可选的，因为在使用 ES2015 语法声明的（非函数或箭头函数的）任何方法或 getter 中，const h = this.$createElement 会被自动注入，因此可以删除 (h) 参数。

要深入了解 JSX 的使用方式，请参阅 Vue.js 文档的 JSX 章节。

忽略文件

.nuxtignore

可以使用 .nuxtignore 让 Nuxt 在构建时忽略项目根目录（rootDir）中的 layout、page、store 和 middleware 文件。.nuxtignore 文件遵循与 .gitignore 和 .eslintignore 相同的规范，每行是一个 glob 模式，指示要忽略哪些文件。

.nuxtignore

# 忽略 foo.vue 布局

layouts/foo.vue

# 忽略文件名以 -ignore.vue 结尾的布局文件

layouts/*-ignore.vue

# 忽略 bar.vue 页面

pages/bar.vue

# 忽略 ignore 文件夹中的页面

pages/ignore/*.vue

# 忽略 bar.js store

store/baz.js

# 忽略匹配 _.test._ 的 store 文件

store/ignore/_.test._

# 忽略 foo 文件夹中除 foo/bar.js 以外的中间件文件

middleware/foo/*.js !middleware/foo/bar.js

ignorePrefix 属性

pages/、layout/、middleware/ 和 store/ 目录中，文件名以 ignorePrefix 属性指定的前缀开头的文件在构建时会被忽略。

默认情况下，所有以 - 开头的文件（如 store/-foo.js 和 pages/-bar.vue）都会被忽略。这样可以在不将其转换为路由、store 等的情况下，将测试、工具和组件等文件与调用方放在同一位置。

ignore 属性

比 ignorePrefix 更易于自定义：ignore 属性中指定的 glob 模式匹配的所有文件在构建时都会被忽略。

nuxt.config.js

export default {
  ignore: 'pages/bar.vue'
}

ignoreOptions

nuxtignore 内部使用 node-ignore。ignoreOptions 会作为 node-ignore 的 options 进行配置。

nuxt.config.js

export default {
  ignoreOptions: {
    ignorecase: false
  }
}

可以通过 nuxt.config.js 中的 extend 选项扩展 nuxt 的 webpack 配置。build 属性的 extend 选项是一个接收两个参数的函数。第一个参数是从 nuxt 的 webpack 配置导出的 webpack config 对象，第二个参数是包含以下布尔属性的 context 对象：{ isDev, isClient, isServer, loaders }。

nuxt.config.js

export default {
  build: {
    extend(config, { isDev, isClient }) {
      // ..
      config.module.rules.push({
        test: /\.(ttf|eot|svg|woff(2)?)(\?[a-z0-9=&.]+)?$/,
        loader: 'file-loader'
      })
      // 如果 `isDev` 为 true，将 webpack 设置为开发模式。
      if (isDev) {
        config.mode = 'development'
      }
    }
  }
}

extend 方法会被调用两次——一次用于客户端打包，一次用于服务器打包。

自定义 chunk 配置

可以在不覆盖默认对象的情况下微调优化配置。

nuxt.config.js

export default {
  build: {
    extend(config, { isClient }) {
      if (isClient) {
        config.optimization.splitChunks.maxSize = 200000
      }
    }
  }
}

检查 webpack 配置

对于复杂项目或调试，有时查看最终的 webpack 配置会很有帮助。幸运的是，可以从项目中运行 nuxt webpack 命令来输出配置。详情请查看 GitHub 拉取请求 #7029 。

添加 webpack 插件

在 nuxt.config.js 文件的 build 选项中，可以像在 webpack.config.js 文件中一样传递 webpack plugins。

本例中添加了 webpack 内置的 ProvidePlugin ，用于自动加载 JavaScript 模块（lodash 和 jQuery），而无需 import 或 require。

nuxt.config.js

import webpack from 'webpack'

export default {
  build: {
    plugins: [
      new webpack.ProvidePlugin({
        // 全局模块
        $: 'jquery',
        _: 'lodash'
      })
    ]
  }
}

注意：在基于 Vue 的应用中可能不需要 jQuery。

使用 Nuxt 还可以控制插件的执行上下文。如果插件打算在 build.extend 中的 client 或 server 构建（或区分 dev 构建和 prod 构建）中运行，也可以手动传递 webpack 插件。

扩展 Webpack 以加载音频文件

音频文件需要通过 file-loader 处理。该加载器已包含在默认 Webpack 配置中，但未配置为处理音频文件。需要在 nuxt.config.js 中扩展默认配置：

nuxt.config.js

export default {
  build: {
    extend(config, ctx) {
      config.module.rules.push({
        test: /\.(ogg|mp3|wav|mpe?g)$/i,
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]'
        }
      })
    }
  }
}

现在可以像这样导入音频文件：<audio :src="require('@/assets/water.mp3')" controls></audio>。

如果只想写 <audio src="@/assets/water.mp3" controls></audio>，需要指示 vue-loader 在通过 src 属性引用时自动请求音频文件：

nuxt.config.js

export default {
  build: {
    loaders: {
      vue: {
        transformAssetUrls: {
          audio: 'src'
        }
      }
    },
    extend(config, ctx) {
      config.module.rules.push({
        test: /\.(ogg|mp3|wav|mpe?g)$/i,
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]'
        }
      })
    }
  }
}

编辑主机和端口号

默认情况下，Nuxt 开发服务器的主机为 localhost（只能从主机内部访问）。要在其他设备上查看应用，需要修改主机。可以在 nuxt.config.js 文件中修改主机。

主机 '0.0.0.0' 指示 Nuxt 解析一个可从主机外部（例如 LAN）访问的主机地址。如果主机指定为字符串 '0'（不是 0）或 '0.0.0.0'，本地 IP 地址将分配给 Nuxt。

nuxt.config.js

export default {
  server: {
    host: '0' // 默认值：localhost
  }
}

也可以将端口号从默认的 3000 更改为其他值。

nuxt.config.js

export default {
  server: {
    port: 8000 // 默认值：3000
  }
}

如果端口号指定为字符串值 '0'（不是 0，而是 falsy），则会为 Nuxt 应用分配一个随机端口。

虽然可以在 nuxt.config.js 文件中修改，但在托管站点时可能会出现问题，因此不推荐这样做。建议直接在 dev 命令中指定主机和端口。

HOST=0 PORT=8000 npm run dev

或在 package.json 中创建脚本。

"scripts": {
  "dev:host": "nuxt --hostname '0' --port 8000"
}

异步配置

虽然推荐使用普通的 export default {} 进行配置，但也可以通过导出一个返回配置对象的异步函数来实现异步配置。

nuxt.config.js

import axios from 'axios'

export default async () => {
  const data = await axios.get('https://api.nuxtjs.dev/posts')
  return {
    head: {
      title: data.title
      //... 其余配置
    }
  }
}

不能在 nuxt.config.js 中使用 axios-module，需要导入 axios 并重新配置。

案例展示

案例研究

用户评价

文档

示例

教程

精通课程

部署

模块

主题

视频课程

公告

团队

发布记录

赞助商

本页导读：

配置

css 属性

样式扩展名

预处理器

外部资源

全局配置

局部配置

PostCSS 插件

JSX

忽略文件

.nuxtignore

ignorePrefix 属性

ignore 属性

ignoreOptions

扩展 webpack 配置

自定义 chunk 配置

检查 webpack 配置

添加 webpack 插件

扩展 Webpack 以加载音频文件

编辑主机和端口号

异步配置

更多配置

本页导读：