理解自定义配置

你可以通过在项目的根目录中添加一个 nuxt.config.js 文件（在本书中我们将其称为 Nuxt 配置文件）来配置你的 Nuxt 应用程序以适应你的项目。如果你使用 Nuxt 脚手架工具，你将默认获得此文件。打开此文件时，你应该会看到以下选项（或属性）：

// nuxt.config.js
export default {
  mode: 'universal',
  target: 'server',
  head: { ... },
  css: [],
  plugins: [],
  components: true,
  buildModules: [],
  modules: [],
  build: {}
}

除了 mode、target、head 和 components 之外，大多数选项都是空的。你可以通过这些选项自定义 Nuxt 以专门适应你的项目。让我们逐个介绍这些选项，然后再介绍其他选项，看看你可以将它们用于什么。

mode 选项

mode 选项用于定义你的应用程序的 “性质” ——是通用应用程序还是 SPA。它的默认值为 universal。如果你使用 Nuxt 开发 SPA，则将此值更改为 spa。本书接下来的章节将重点介绍通用模式，第十五章 “使用 Nuxt 创建 SPA” 除外。

target 选项

target 选项用于设置你的应用程序的部署目标——是部署为服务器端渲染应用程序还是静态生成应用程序。它的默认值为 server，表示服务器端渲染部署。本书中大多数示例应用程序的部署目标都是服务器端渲染。我们将在一些章节（尤其是最后一章——第十八章 “使用 CMS 和 GraphQL 创建 Nuxt 应用”）中也将以静态生成部署为目标。

head 选项

head 选项用于定义应用程序 <head> 块中的所有默认 meta 标签。如果你使用 Nuxt 脚手架工具，你将在 Nuxt 配置文件中获得以下自定义 head 配置：

// nuxt.config.js
export default {
  head: {
    title: process.env.npm_package_name || '',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { hid: 'description', name: 'description', content:
        process.env.npm_package_description || '' }
    ],
    link: [
      { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }
    ]
  }
}

你可以修改上述配置或添加更多自定义配置——例如，添加你的项目所需的某些 JavaScript 和 CSS 库：

// nuxt.config.js
export default {
  head: {
    titleTemplate: '%s - Nuxt App',
    meta: [
      //...
    ],
    script: [
      { src: 'https://cdnjs.cloudflare.com/.../jquery.min.js' },
      { src: 'https://cdn.jsdelivr.net/.../foundation.min.js' },
    ],
    link: [
      { rel: 'stylesheet', href:
        'https://cdn.jsdelivr.net/.../foundation.min.css' },
    ]
  }
}

我们将在第三章 “添加 UI 框架” 和第四章 “添加视图、路由和过渡效果” 中更详细地介绍此选项。请注意，jQuery 是 Foundation (Zurb) 的核心依赖项，我们将在第三章 “添加 UI 框架” 中探讨它。因此，目前你需要先在你的项目中安装 jQuery 才能使用 Foundation。这在未来的版本中可能会成为可选的。

css 选项

css 选项用于添加全局 CSS 文件。这些文件可以是 .css、.less 或 .scss 文件。它们也可以是直接从你的项目 Node.js /node_modules/ 目录加载的模块和库。例如，考虑以下配置：

// nuxt.config.js
export default {
  css: [
    'jquery-ui-bundle/jquery-ui.min.css',
    '@/assets/less/styles.less',
    '@/assets/scss/styles.scss'
  ]
}

在上面的配置中，我们加载了安装在 /node_modules/ 目录中的 jQuery UI 模块中的 CSS 文件，以及存储在 /assets/ 目录中的 Less 和 Sass 文件。请注意，如果你使用 .less 和 .scss 文件编写样式，你需要安装 Less 和 Sass 模块及其 webpack 加载器，如下所示：

$ npm i less less-loader --save-dev
$ npm i node-sass --save-dev
$ npm i sass-loader --save-dev

我们将在第三章 “添加 UI 框架” 和第四章 “添加视图、路由和过渡效果” 中更多地使用此选项。

plugins 选项

plugins 选项用于添加在根 Vue 实例之前运行的 JavaScript 插件。例如：

// nuxt.config.js
export default {
  plugins: ['~/plugins/vue-notifications']
}

我们通常将此选项与我们在上一节中介绍的 /plugins/ 目录一起使用。我们将在第六章 “编写插件和模块” 中大量使用此选项。

components 选项

components 选项用于设置是否自动导入 /components/ 目录中的组件。如果你有大量组件需要导入到布局或页面中，此选项非常有用。如果将此选项设置为 true，则无需手动导入它们。它的默认值为 false。本书中的所有应用程序都将此选项设置为 true。

有关此选项的更多信息和（高级）用法，请访问 https://github.com/nuxt/components。

buildModules 选项

buildModules 选项用于注册仅在开发和构建时需要的构建模块。请注意，在本书中，我们只会在第六章 “编写插件和模块” 中利用 Nuxt 社区的一些模块并创建 Node.js 运行时所需的自定义模块。有关 buildModules 选项和仅用于构建时的构建模块的更多信息，请访问 https://nuxtjs.org/guide/modules#build-only-modules。

modules 选项

modules 选项用于向你的项目添加 Nuxt 模块。例如：

// nuxt.config.js
export default {
  modules: [
    '@nuxtjs/axios',
    '~/modules/example.js'
  ]
}

我们也可以使用此选项直接创建内联模块：

// nuxt.config.js
export default {
  modules: [
    function () {
      //...
    }
  ]
}

Nuxt 模块本质上是 JavaScript 函数，就像插件一样。我们将在第六章 “编写插件和模块” 中讨论它们之间的区别。就像经常与 /plugins/ 目录一起使用的 plugins 选项一样，modules 选项也经常与 /modules/ 目录一起使用。我们将在第六章 “编写插件和模块” 中经常使用此选项。

build 选项

build 选项用于自定义用于构建你的 Nuxt 应用程序的 webpack 配置，以你喜欢的方式进行构建。例如，你可能希望在你的项目中全局安装 jQuery，这样你就不必在每次需要时都使用 import 语句。你可以使用 webpack 的 ProvidePlugin 函数自动加载 jQuery，如下所示：

// nuxt.config.js
import webpack from 'webpack'

export default {
  build: {
    plugins: [
      new webpack.ProvidePlugin({
        $: "jquery"
      })
    ]
  }
}

我们将在第四章 “添加视图、路由和过渡效果”、第六章 “编写插件和模块” 以及第十四章 “使用代码检查器、格式化工具和部署命令” 中再次使用此 build 选项。

有关你可以使用此选项为你的 Nuxt 应用程序执行的操作的更多详细信息和示例，请访问 https://nuxtjs.org/api/configuration-build。

有关 webpack 的 ProvidePlugin 函数的更多信息，请访问 https://webpack.js.org/plugins/provide-plugin/。如果你是 webpack 的新手，我们建议你访问并学习 https://webpack.js.org/guides/。

以下部分概述了你可以用来进一步和更具体地自定义你的 Nuxt 应用程序的一些附加选项。让我们探索一些在你的项目中可能有用的选项。本书中经常使用其中的一些选项。让我们开始吧！

dev 选项

dev 选项用于定义你的应用程序的开发或生产模式。它不会添加到 Nuxt 配置文件中，但你可以在需要时手动添加它。它只接受布尔类型，其默认设置为 true。在使用 nuxt 命令时，它始终强制为 true，而在使用 nuxt build、nuxt start 和 nuxt generate 命令时，它始终强制为 false。

因此，从技术上讲，你无法自定义它，但你可以在 Nuxt 模块中使用此选项，如下所示：

// modules/sample.js
export default function (moduleOptions) {
  console.log(this.options.dev)
}

你将获得 true 或 false，具体取决于你使用的 Nuxt 命令。我们将在第六章 “编写插件和模块” 中介绍此模块。或者，当你将 Nuxt 作为包导入到服务器端框架中时，可以使用此选项，如下所示：

// server/index.js
import { Nuxt, Builder } from 'nuxt'
import config from './nuxt.config.js'

const nuxt = new Nuxt(config)

if (nuxt.options.dev) {
  new Builder(nuxt).build()
}

当 dev 选项为 true 时，将运行 new Builder(nuxt).build() 这行代码。我们将在第八章 “添加服务端框架” 中介绍服务器端框架。

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/dev/ 目录下找到此选项的示例应用程序。

rootDir 选项

rootDir 选项用于定义你的 Nuxt 应用程序的工作区。例如，假设你的项目位于以下位置：

/var/www/html/my-project/

那么，你的项目的 rootDir 选项的默认值为 /var/www/html/my-project/。但是，你可以通过在你的 package.json 文件中使用 Nuxt 命令来更改它，如下所示：

{
  "scripts": {
    "dev": "nuxt ./app/"
  }
}

现在，你的 Nuxt 应用程序的工作区位于 /var/www/html/my-project/app/，你的应用程序结构已变为以下形式：

-| my-project/
---| node_modules/
---| app/
------| nuxt.config.js
------| pages/
------| components/
------| ...
---| package.json

请注意，现在 Nuxt 配置文件必须放在 /app/ 目录中。我们将在第十四章 “使用代码检查器、格式化工具和部署命令” 中介绍 Nuxt 命令。

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/rooDir/ 目录下找到此选项的示例应用程序。

srcDir 选项

srcDir 选项用于定义你的 Nuxt 应用程序的源目录。srcDir 的默认值是 rootDir 的值。你可以按如下方式更改它：

// nuxt.config.js
export default {
  srcDir: 'src/'
}

现在，你的应用程序结构已变为以下形式：

-| my-project/
---| node_modules/
---| src/
------| pages/
------| components/
------| ...
---| nuxt.config.js
---| package.json

请注意，Nuxt 配置文件位于 /src/ 目录之外。

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/srcDir/ 目录下找到此选项的示例应用程序。

server 选项

server 选项用于配置你的 Nuxt 应用程序的服务器连接变量。它具有以下默认服务器连接详细信息：

export default {
  server: {
    port: 3000,
    host: 'localhost',
    socket: undefined,
    https: false,
    timing: false
  }
}

你可以按如下方式更改它们：

export default {
  server: {
    port: 8080,
    host: '0.0.0.0'
  }
}

现在，你的应用程序运行在 0.0.0.0:8080。

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/server/ 目录下找到此选项的示例应用程序。

env 选项

env 选项用于为你的 Nuxt 应用程序的客户端和服务器端设置环境变量。此选项的默认值是一个空对象 {}。当你在项目中使用 axios 时，此选项非常有用。

考虑以下示例：

// nuxt.config.js
export default {
  env: {
    baseUrl: process.env.BASE_URL || 'http://localhost:3000'
  }
}

然后，你可以在 axios 插件中使用 env 属性，如下所示：

// plugins/axios.js
import axios from 'axios'

export default axios.create({
  baseURL: process.env.baseUrl
})

现在，baseURL 选项设置为 localhost:3000，或者如果定义了 BASE_URL 环境变量，则设置为该环境变量的值。我们可以在 package.json 中设置 BASE_URL，如下所示：

"scripts": {
  "start": "cross-env BASE_URL=https://your-domain-name.com nuxt start"
}

你需要安装 cross-env 才能使前面的示例在 Windows 上工作：

$ npm i cross-env --save-dev

我们将在第六章 “编写插件和模块” 中介绍插件。在本书中创建跨域应用程序时，我们将经常使用此 env 选项。

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/env/ 目录下找到此选项的示例应用程序。

router 选项

router 选项用于覆盖 Vue Router 的默认 Nuxt 配置。默认的 Vue Router 配置如下：

{
  mode: 'history',
  base: '/',
  routes: [],
  routeNameSplitter: '-',
  middleware: [],
  linkActiveClass: 'nuxt-link-active',
  linkExactActiveClass: 'nuxt-link-exact-active',
  linkPrefetchedClass: false,
  extendRoutes: null,
  scrollBehavior: null,
  parseQuery: false,
  stringifyQuery: false,
  fallback: false,
  prefetchLinks: true
}

你可以按如下方式更改此配置：

// nuxt.config.js
export default {
  router: {
    base: '/app/'
  }
}

现在，你的应用程序运行在 localhost:3000/app/。

有关此属性及其余配置的更多信息，请访问 https://nuxtjs.org/api/configuration-router。

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/router/ 目录下找到此选项的示例应用程序。

dir 选项

dir 选项用于在我们的 Nuxt 应用程序中定义自定义目录。默认目录如下：

{
  assets: 'assets',
  layouts: 'layouts',
  middleware: 'middleware',
  pages: 'pages',
  static: 'static',
  store: 'store'
}

你可以按如下方式更改它们：

// nuxt.config.js
export default {
  dir: {
    assets: 'nuxt-assets',
    layouts: 'nuxt-layouts',
    middleware: 'nuxt-middleware',
    pages: 'nuxt-pages',
    static: 'nuxt-static',
    store: 'nuxt-store'
  }
}

现在，你可以使用上述自定义目录，如下所示：

-| app/
---| nuxt-assets/
---| components/
---| nuxt-layouts/
---| nuxt-middleware/
---| node_modules/
---| nuxt-pages/
---| plugins/
---| modules/
---| nuxt-static/
---| nuxt-store/
---| nuxt.config.js
---| package.json
---| README.md

你可以在我们的 GitHub 仓库的 /chapter-2/configuration/dir/ 目录下找到此选项的示例应用程序。

loading 选项

loading 选项用于自定义你的 Nuxt 应用程序中的默认加载组件。如果你不想使用此默认加载组件，你可以将其设置为 false，如下所示：

// nuxt.config.js
export default {
  loading: false
}

我们将在第四章 “添加视图、路由和过渡效果” 中更详细地介绍此选项。

pageTransition 和 layoutTransition 选项

pageTransition 和 layoutTransition 选项用于自定义你的 Nuxt 应用程序中页面和布局过渡的默认属性。页面过渡的默认属性设置如下：

{
  name: 'page',
  mode: 'out-in',
  appear: false,
  appearClass: 'appear',
  appearActiveClass: 'appear-active',
  appearToClass: 'appear-to'
}

布局过渡的默认属性设置如下：

{
  name: 'layout',
  mode: 'out-in'
}

你可以按如下方式更改它们：

// nuxt.config.js
export default {
  pageTransition: {
    name: 'fade'
  },
  layoutTransition: {
    name: 'fade-layout'
  }
}

我们将在第四章 “添加视图、路由和过渡效果” 中更详细地介绍这些选项。

generate 选项

generate 选项用于告诉 Nuxt 如何为静态 Web 应用程序生成动态路由。动态路由是在 Nuxt 中使用下划线创建的路由。我们将在第四章 “添加视图、路由和过渡效果” 中介绍这种类型的路由。如果我们希望将我们的 Nuxt 应用程序导出为静态 Web 应用程序或 SPA，而不是将 Nuxt 用作通用应用程序 (SSR)，我们会将 generate 选项与 Nuxt 爬虫无法自动检测到的动态路由一起使用。例如，如果爬虫无法检测到你的应用程序中可能存在以下动态路由（分页）：

/posts/pages/1
/posts/pages/2
/posts/pages/3

然后，你可以使用此 generate 选项为你生成和转换每个路由的内容到 HTML 文件，如下所示：

// nuxt.config.js
export default {
  generate: {
    routes: [
      '/posts/pages/1',
      '/posts/pages/2',
      '/posts/pages/3'
    ]
  }
}

我们将在第十五章 “创建 Nuxt SPA” 和第十八章 “使用 CMS 和 GraphQL 创建 Nuxt 应用” 中向你展示如何使用此选项生成爬虫无法检测到的路由。

有关此 generate 选项的更多信息和更高级的用法，请访问 https://nuxtjs.org/api/configuration-generate。

我们将在后续章节中逐步介绍和探索其他配置选项。但是，这些是你目前应该了解的基本自定义配置选项。现在，让我们在下一个主题中进一步探索 webpack 的静态资源服务。