配置

nuxt.config

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

迁移

1. 你应当迁移到新的 defineNuxtConfig 函数，该函数提供了类型化的配置 schema。
   Nuxt 2Nuxt 3

   export default {
     // ...
   }
   

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

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

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

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

ESM 语法

Nuxt 3 是一个 原生 ESM 框架。虽然 unjs/jiti 在加载 nuxt.config 文件时提供了半兼容性，但请避免在此文件中使用 require 和 module.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 来保持原名。

TypeScript

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

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

迁移

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

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

2. 运行 npx nuxt prepare 来生成 tsconfig 文件。
3. 按照文档中的说明安装 Volar（见 docs）。

Vue 变更

在推荐的 Vue 最佳实践方面以及 Vue 2 与 Vue 3 之间存在许多破坏性更改。

建议阅读 Vue 3 迁移指南，尤其是 破坏性更改列表。

目前无法在 Nuxt 3 中使用 Vue 3 迁移构建。

Vuex

Nuxt 不再提供 Vuex 集成。官方推荐改用 pinia，它通过一个 Nuxt 模块 提供了内置的 Nuxt 支持。在此处了解有关 pinia 的更多信息。

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

安装 @pinia/nuxt 模块：

yarn add pinia @pinia/nuxt

在你的 nuxt 配置中启用该模块：

import { defineNuxtConfig } from 'nuxt/config'

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

在应用根目录创建一个 store 文件夹：

import { defineStore } from 'pinia'

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

创建一个 插件 文件以在全局使用你的 store：

import { useMainStore } from '~/store'

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

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

完成后，你需要向 Nuxt 应用添加以下插件：

import store from '~/store'

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

对于大型应用，此迁移可能会涉及大量工作。如果更新 Vuex 仍然造成阻碍，你可以考虑使用社区模块：nuxt3-vuex-module，它应该可以开箱即用。