配置

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

`nuxt.config`

你的 Nuxt 应用的起点仍然是 nuxt.config 文件。

Nuxt 配置将通过 unjs/jiti 和 unjs/c12 加载。 ::

迁移

你应该迁移到新的 defineNuxtConfig 函数，它提供了带类型提示的配置 schema。

export default {
  // ...
}

export default defineNuxtConfig({
  // ...
})

如果你之前使用 router.extendRoutes，可以迁移到新的 pages:extend 钩子：

export default {
  router: {
    extendRoutes (routes) {
      //
    },
  },
}

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (routes) {
      //
    },
  },
})

如果你之前使用 router.routeNameSplitter，可以通过在新的 pages:extend 钩子中更新路由名称生成逻辑来达到相同效果：

export default {
  router: {
    routeNameSplitter: '/',
  },
}

import { createResolver } from '@nuxt/kit'

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (routes) {
      const routeNameSplitter = '/'
      const root = createResolver(import.meta.url).resolve('./pages')

      function updateName (routes) {
        if (!routes) {
          return
        }

        for (const route of routes) {
          const relativePath = route.file.substring(root.length + 1)
          route.name = relativePath.slice(0, -4).replace(/\/index$/, '').replace(/\//g, routeNameSplitter)

          updateName(route.children)
        }
      }
      updateName(routes)
    },
  },
})

ESM 语法

Nuxt 3 是一个原生 ESM 框架。尽管 unjs/jiti 在加载 nuxt.config 文件时提供了部分兼容性，但请避免在该文件中使用任何 require 和 module.exports。

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

异步配置

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

Dotenv

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

模块

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

迁移

将所有 buildModules 移入 modules。
检查模块的 Nuxt 3 兼容性。
如果你有任何指向某个目录的本地模块，应将其更新为指向入口文件：

  export default defineNuxtConfig({
    modules: [
-     '~/modules/my-module'
+     '~/modules/my-module/index'
    ]
  })

如果你是模块作者，可以查看关于模块兼容性的更多信息以及我们的模块作者指南。 ::

目录变更

用于存储静态资源的 static/ 已重命名为 public/。你可以将 static 目录重命名为 public，或者通过在 nuxt.config 中设置 dir.public 来保留原名。

TypeScript

如果你使用 Nuxt 的 TypeScript 集成，迁移应用会容易得多。这并不代表你需要用 TypeScript 编写应用，只是说 Nuxt 会为你的编辑器提供自动的类型提示。

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

Nuxt 可以使用 nuxt typecheck 命令通过 vue-tsc 对你的应用进行类型检查。

迁移

创建一个包含以下内容的 tsconfig.json：

{
  "files": [],
  "references": [
    {
      "path": "./.nuxt/tsconfig.app.json"
    },
    {
      "path": "./.nuxt/tsconfig.server.json"
    },
    {
      "path": "./.nuxt/tsconfig.shared.json"
    },
    {
      "path": "./.nuxt/tsconfig.node.json"
    }
  ]
}

运行 npx nuxt prepare 生成 tsconfig 文件。
按照文档中的说明安装 Volar。

Vue 变更

在 Vue 最佳实践方面有许多变化，Vue 2 和 3 之间也存在许多破坏性变更。建议阅读 Vue 3 迁移指南，尤其是破坏性变更列表。目前无法在 Nuxt 3 中使用 Vue 3 迁移构建。

Vuex

Nuxt 不再提供 Vuex 集成。官方 Vue 推荐改用 pinia，它已通过 Nuxt 模块内置支持。在此了解更多关于 pinia 的内容。使用 pinia 提供全局状态管理的一个简单方式是：安装 @pinia/nuxt 模块：

Terminal

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` 是 store 实例
      this.counter++
    },
  },
})

创建一个 plugin 文件来全局化你的 store：

app/plugins/pinia.ts

import { useMainStore } from '~/store'

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

如果你想继续使用 Vuex，可以按照这些步骤手动迁移到 Vuex 4。完成后，你需要向你的 Nuxt 应用添加以下插件：

app/plugins/vuex.ts

import store from '~/store'

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

对于较大的应用，此迁移可能需要大量工作。如果更新 Vuex 仍然有阻碍，你可能想使用社区模块：nuxt3-vuex-module，它应该开箱即用。