---
title: "配置"
description: "了解如何将 Nuxt 2 的配置迁移到 Nuxt 3 的新配置。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/migration/configuration"
---
# 配置

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

## `nuxt.config`

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

::note
Nuxt 配置将使用 [`unjs/jiti`](https://github.com/unjs/jiti) 和 [`unjs/c12`](https://github.com/unjs/c12) 加载。
::

### 迁移

1. 你应当迁移到新的 `defineNuxtConfig` 函数，该函数提供了类型化的配置 schema。
   ::code-group
   ```ts [Nuxt 2]
   export default {
     // ...
   }
   ```

   ```ts [Nuxt 3]
   export default defineNuxtConfig({
     // ...
   })
   ```
   ::
2. 如果你之前使用了 `router.extendRoutes`，可以迁移到新的 `pages:extend` 钩子：
   ::code-group
   ```ts [Nuxt 2]
   export default {
     router: {
       extendRoutes (routes) {
         //
       },
     },
   }
   ```

   ```ts [Nuxt 3]
   export default defineNuxtConfig({
     hooks: {
       'pages:extend' (routes) {
         //
       },
     },
   })
   ```
   ::
3. 如果你之前使用了 `router.routeNameSplitter`，可以通过在新的 `pages:extend` 钩子中更新路由名称生成逻辑来实现相同的效果：
   ::code-group
   ```ts [Nuxt 2]
   export default {
     router: {
       routeNameSplitter: '/',
     },
   }
   ```

   ```ts [Nuxt 3]
   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 的框架](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/esm)。尽管 [`unjs/jiti`](https://github.com/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. 如果你有任何指向目录的本地模块，应将其更新为指向入口文件：

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

::tip
如果你是模块作者，可以查看[有关模块兼容性的更多信息](https://nuxt.zhcndoc.com/docs/4.x/migration/module-authors)和[我们的模块作者指南](https://nuxt.zhcndoc.com/docs/4.x/guide/modules)。
::

## 目录变更

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

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/public"}
::

## TypeScript

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

你可以[在文档中](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/typescript)阅读有关 Nuxt TypeScript 支持的更多信息。

::note
Nuxt 可以使用 [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) 通过 `nuxt typecheck` 命令对你的应用进行类型检查。
::

### 迁移

1. 创建一个包含以下内容的 `tsconfig.json`：
   ```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. 按照[文档](https://nuxt.zhcndoc.com/docs/4.x/getting-started/installation#prerequisites)中的说明安装 Volar。

## Vue 变更

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

建议阅读 [Vue 3 迁移指南](https://v3-migration.vuejs.org)，尤其是 [破坏性更改列表](https://v3-migration.vuejs.org/breaking-changes/)。

目前无法在 Nuxt 3 中使用 [Vue 3 迁移构建](https://v3-migration.vuejs.org/migration-build.html)。

## Vuex

Nuxt 不再提供 Vuex 集成。官方推荐改用 `pinia`，它通过一个 [Nuxt 模块](https://pinia.vuejs.org/ssr/nuxt.html) 提供了内置的 Nuxt 支持。[在此处了解有关 pinia 的更多信息](https://pinia.vuejs.org)。

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

安装 [`@pinia/nuxt`](https://nuxt.zhcndoc.com/modules/pinia) 模块：

```bash [Terminal]
yarn add pinia @pinia/nuxt
```

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

```ts [nuxt.config.ts]
import { defineNuxtConfig } from 'nuxt/config'

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

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

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

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

创建一个 [插件](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/plugins) 文件，以便在全局范围内使用你的 store：

```ts [app/plugins/pinia.ts]
import { useMainStore } from '~/store'

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

如果你想继续使用 Vuex，可以按照[这些步骤](https://vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html)手动迁移到 Vuex 4。

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

```ts [app/plugins/vuex.ts]
import store from '~/store'

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

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


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.