配置
nuxt.config
您的 Nuxt 应用程序的起点仍然是 nuxt.config
文件。
迁移
- 您应该迁移到新的
defineNuxtConfig
函数,它提供了类型化的配置模式。export default { // ... }
- 如果您正在使用
router.extendRoutes
,您可以迁移到新的pages:extend
钩子export default { router: { extendRoutes (routes) { // } } }
- 如果您正在使用
router.routeNameSplitter
,您可以通过更新新的pages:extend
钩子中的路由名称生成逻辑来实现相同的结果export default { router: { routeNameSplitter: '/' } }
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 支持。
vue-tsc
和 nuxi typecheck
命令对您的应用程序进行类型检查。迁移
- 创建一个包含以下内容的
tsconfig.json
{ "extends": "./.nuxt/tsconfig.json" }
- 运行
npx nuxi prepare
以生成.nuxt/tsconfig.json
。 - 按照文档中的说明安装 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 配置中启用该模块
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,它应该可以开箱即用。