通过 100+ 技巧学习 Nuxt!

配置

了解如何从 Nuxt 2 迁移到 Nuxt 3 的新配置。

nuxt.config

您的 Nuxt 应用程序的起点仍然是 nuxt.config 文件。

Nuxt 配置将使用 unjs/jitiunjs/c12 加载。

迁移

  1. 您应该迁移到新的 defineNuxtConfig 函数,它提供了类型化的配置模式。
    export default {
      // ...
    }
    
  2. 如果您正在使用 router.extendRoutes,您可以迁移到新的 pages:extend 钩子
    export default {
      router: {
        extendRoutes (routes) {
          //
        }
      }
    }
    
  3. 如果您正在使用 router.routeNameSplitter,您可以通过更新新的 pages:extend 钩子中的路由名称生成逻辑来实现相同的结果
    export default {
      router: {
        routeNameSplitter: '/'
      }
    }
    

ESM 语法

Nuxt 3 是一个 ESM 原生框架。尽管 unjs/jiti 在加载 nuxt.config 文件时提供半兼容性,但请避免在此文件中使用 requiremodule.exports

  1. module.exports 更改为 export default
  2. const lib = require('lib') 更改为 import lib from 'lib'

异步配置

为了使 Nuxt 加载行为更可预测,异步配置语法已被弃用。请考虑使用 Nuxt 钩子进行异步操作。

Dotenv

Nuxt 内置支持加载 .env 文件。避免直接从 nuxt.config 中导入它。

模块

Nuxt 和 Nuxt 模块现在仅在构建时可用。

迁移

  1. 将所有 buildModules 移动到 modules 中。
  2. 检查模块的 Nuxt 3 兼容性。
  3. 如果您有任何指向目录的本地模块,您应该更新它以指向入口文件
  export default defineNuxtConfig({
    modules: [
-     '~/modules/my-module'
+     '~/modules/my-module/index'
    ]
  })
如果您是模块作者,您可以查看更多关于模块兼容性的信息我们的模块作者指南

目录变更

static/(用于存储静态资源)已被重命名为 public/。您可以将您的 static 目录重命名为 public,或者通过在您的 nuxt.config 中设置 dir.public 来保留该名称。

文档 > 指南 > 目录结构 > Public中阅读更多信息。

TypeScript

如果您使用 Nuxt 的 TypeScript 集成,迁移您的应用程序将会容易得多。这并不意味着您需要用 TypeScript 编写您的应用程序,只是 Nuxt 将为您的编辑器提供自动类型提示。

您可以在文档中阅读更多关于 Nuxt 的 TypeScript 支持。

Nuxt 可以使用 vue-tscnuxi typecheck 命令对您的应用程序进行类型检查。

迁移

  1. 创建一个包含以下内容的 tsconfig.json
    {
      "extends": "./.nuxt/tsconfig.json"
    }
    
  2. 运行 npx nuxi prepare 以生成 .nuxt/tsconfig.json
  3. 按照文档中的说明安装 Volar。

Vue 变更

Vue 最佳实践的推荐做法发生了一些变化,Vue 2 和 3 之间也存在一些重大更改。

建议阅读 Vue 3 迁移指南,特别是重大更改列表

目前无法将 Vue 3 迁移构建与 Nuxt 3 一起使用。

Vuex

Nuxt 不再提供 Vuex 集成。相反,Vue 官方建议使用 pinia,它通过 Nuxt 模块内置了 Nuxt 支持。 在此处了解更多关于 pinia 的信息

使用 pinia 提供全局状态管理的一个简单方法是

安装 @pinia/nuxt 模块

终端
yarn add pinia @pinia/nuxt

在您的 nuxt 配置中启用该模块

nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config';

export default defineNuxtConfig({
  modules: ['@pinia/nuxt']
})

在您的应用程序的根目录创建一个 store 文件夹

store/index.ts
import { defineStore } from 'pinia'

export const useMainStore = defineStore('main', {
  state: () => ({
    counter: 0,
  }),
  actions: {
    increment() {
      // `this` is the store instance
      this.counter++
    },
  },
})

创建一个插件文件以全局化您的 store

plugins/pinia.ts
import { useMainStore } from '~/store'

export default defineNuxtPlugin(({ $pinia }) => {
  return {
    provide: {
      store: useMainStore($pinia)
    }
  }
})

如果您想继续使用 Vuex,您可以按照这些步骤手动迁移到 Vuex 4。

完成后,您将需要在您的 Nuxt 应用程序中添加以下插件

plugins/vuex.ts
import store from '~/store'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(store);
})

对于较大的应用程序,此迁移可能需要大量工作。如果更新 Vuex 仍然造成障碍,您可能需要使用社区模块:nuxt3-vuex-module,它应该可以开箱即用。