55K

升级指南

了解如何升级到最新的 Nuxt 版本。

升级 Nuxt

最新版本

要将 Nuxt 升级到 最新版本，使用 nuxi upgrade 命令。

npx nuxi upgrade

每日构建渠道

要使用最新的 Nuxt 构建并在发布之前测试功能，请阅读 每日构建渠道 指南。

当前每日构建渠道的 latest 标签正在跟踪 Nuxt v4 分支，这意味着它现在特别容易出现破坏性更改 - 请小心！您可以选择加入 3.x 分支每日构建，使用 "nuxt": "npm:nuxt-nightly@3x"。

测试 Nuxt 4

Nuxt 4 的发布日期 待通知。这取决于在 Nitro 的重大发布后有足够的时间进行社区测试。您可以在 这个 PR 中跟踪 Nitro 发布的进展。

在发布之前，您可以测试许多 Nuxt 4 在 Nuxt 3.12+ 版本中的破坏性更改。

观看 Alexander Lichter 展示如何选择加入 Nuxt 4 的破坏性更改的视频。

选择加入 Nuxt 4

首先，将 Nuxt 升级到 最新版本。

然后，您可以将 compatibilityVersion 设置为匹配 Nuxt 4 的行为：

nuxt.config.ts
export default 
defineNuxtConfig
({
  
future
: {
    
compatibilityVersion
: 4,
  },
  // 要重新启用 _所有_ Nuxt v3 的行为，请设置以下选项：
  // srcDir: '.',
  // dir: {
  //   app: 'app'
  // },
  // experimental: {
  //   scanPageMeta: 'after-resolve',
  //   sharedPrerenderData: false,
  //   compileTemplate: true,
  //   resetAsyncDataToUndefined: true,
  //   templateUtils: true,
  //   relativeWatchPaths: true,
  //   normalizeComponentNames: false,
  //   defaults: {
  //     useAsyncData: {
  //       deep: true
  //     }
  //   }
  // },
  // unhead: {
  //   renderSSRHeadOptions: {
  //     omitLineBreaks: false
  //   }
  // }
})

当您将 compatibilityVersion 设置为 4 时，您 Nuxt 配置中的默认值将更改为选择加入 Nuxt v4 的行为，但您可以在测试时逐项重新启用 Nuxt v3 的行为，遵循上述注释掉的行。如果有问题，请报告，以便我们在 Nuxt 或生态系统中解决它们。

迁移到 Nuxt 4

破坏性或重大更改将在此处标记，并附有向后/向前兼容的迁移步骤。

此部分在最终发布之前会有所更改，因此如果您正在使用 compatibilityVersion: 4 测试 Nuxt 4，请定期回来查看此处。

使用 Codemods 进行迁移

为了便于升级过程，我们与 Codemod 团队合作，使用一些开源的 codemods 自动化许多迁移步骤。

如果遇到任何问题，请向 Codemod 团队报告，使用 npx codemod feedback 🙏

要获取完整的 Nuxt 4 codemods 列表、每个 codemod 的详细信息、它们的来源及其运行的各种方法，请访问 Codemod 注册表。

您可以使用以下 codemod 配方运行本指南中提到的所有 codemods：

npx codemod@latest nuxt/4/migration-recipe

此命令将按顺序执行所有 codemods，并可以选择不运行任何您不想运行的 codemod。每个 codemod 也在下面列出，并可以独立执行。

新目录结构

🚦 影响程度：重大

Nuxt 现在默认使用新目录结构，具有向后兼容性（因此如果 Nuxt 检测到您使用的是旧结构，例如顶级 pages/ 目录，则此新结构将不适用）。

👉 查看完整 RFC

变化内容
  • 新的 Nuxt 默认 srcDir 为 app/，大多数内容都是从此处解析。
  • serverDir 现在默认值为 <rootDir>/server 而不是 <srcDir>/server。
  • layers/、modules/ 和 public/ 默认相对于 <rootDir> 解析。
  • 如果使用 Nuxt Content v2.13+，content/ 相对于 <rootDir> 解析。
  • 新增 dir.app，该目录用于查找 router.options.ts 和 spa-loading-template.html - 默认值为 <srcDir>/。
一个 v4 文件夹结构的示例。
.output/
.nuxt/
app/
  assets/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  utils/
  app.config.ts
  app.vue
  router.options.ts
content/
layers/
modules/
node_modules/
public/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts

👉 有关更多详细信息，请查看 实施此更改的 PR。

更改原因
  1. 性能 - 将所有代码放在存储库的根目录中会导致 .git/ 和 node_modules/ 文件夹被扫描/包含在 FS 观察者中，这可能会显著延迟在非 Mac OS 上的启动。
  2. IDE 类型安全性 - server/ 和应用程序的其余部分在两个完全不同的上下文中运行，具有不同的全局导入，确保 server/ 不在与应用程序其余部分相同的文件夹中是确保您在 IDE 中获得良好自动完成功能的第一步。
迁移步骤
  1. 创建一个新的名为 app/ 的目录。
  2. 将 assets/、components/、composables/、layouts/、middleware/、pages/、plugins/ 和 utils/ 文件夹及 app.vue、error.vue、app.config.ts 移动到该目录下。如果您有 app/router-options.ts 或 app/spa-loading-template.html，这些路径保持不变。
  3. 确保您的 nuxt.config.ts、content/、layers/、modules/、public/ 和 server/ 文件夹保持在 app/ 文件夹之外，在项目根目录下。
  4. 记得更新任何第三方配置文件以适应新目录结构，例如您的 tailwindcss 或 eslint 配置（如果需要 - @nuxtjs/tailwindcss 应该会自动正确配置 tailwindcss）。
您可以通过运行 npx codemod@latest nuxt/4/file-structure 来自动化此迁移。

然而，迁移并不是必需的。如果您希望保留当前的文件夹结构，Nuxt 应该能够自动检测到它。（如果没有，请提出问题。）唯一的例外是，如果您已经有自定义的 srcDir。在这种情况下，您应该意识到，您的 modules/、public/ 和 server/ 文件夹将从您的 rootDir 而不是您的自定义 srcDir 中解析。如果需要，您可以通过配置 dir.modules、dir.public 和 serverDir 来覆盖此设置。

您还可以使用以下配置强制使用 v3 文件夹结构：

nuxt.config.ts
export default defineNuxtConfig({
  // 这将新的 srcDir 默认值从 `app` 还原回您的根目录
  srcDir: '.',
  // 这指定了 `app/router.options.ts` 和 `app/spa-loading-template.html` 的目录前缀
  dir: {
    app: 'app'
  }
})

规范化组件名称

🚦 影响程度：中等

Vue 现在将生成与 Nuxt 组件命名模式匹配的组件名称。

变化内容

默认情况下，如果您没有手动设置，Vue 将为组件分配一个与组件文件名匹配的组件名称。

目录结构
├─ components/
├─── SomeFolder/
├───── MyComponent.vue

在这种情况下，对于 Vue 而言，组件名称将是 MyComponent。如果您想在其中使用 <KeepAlive> 或在 Vue DevTools 中识别它，您需要使用这个名称。

但是，为了自动导入它，您需要使用 SomeFolderMyComponent。

通过此更改，这两个值将匹配，Vue 将生成与 Nuxt 组件命名模式相匹配的组件名称。

迁移步骤

确保在任何使用 @vue/test-utils 的 findComponent 测试中和任何依赖于组件名称的 <KeepAlive> 中使用更新的名称。

或者，现在您可以通过以下方式禁用此行为：

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
normalizeComponentNames
: false
  }
})

解析后扫描页面元数据

🚦 影响程度：最小

变化内容

我们现在在调用 pages:extend 钩子后扫描页面元数据（在 definePageMeta 中定义），而不是之前。

更改原因

这样做是为了允许扫描用户希望在 pages:extend 中添加的页面的元数据。我们仍然提供在新的 pages:resolved 钩子中更改或覆盖页面元数据的机会。

迁移步骤

如果您想覆盖页面元数据，请在 pages:resolved 中执行，而不是在 pages:extend 中。

  export default defineNuxtConfig({
    hooks: {
-     'pages:extend'(pages) {
+     'pages:resolved'(pages) {
        const myPage = pages.find(page => page.path === '/')
        myPage.meta ||= {}
        myPage.meta.layout = 'overridden-layout'
      }
    }
  })

或者，您可以通过以下方式恢复先前的行为：

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
scanPageMeta
: true
  }
})

共享预渲染数据

🚦 影响程度：中等

变化内容

我们启用了一个先前实验性的功能，以共享来自 useAsyncData 和 useFetch 调用的数据，跨不同页面共享。请参阅 原始 PR。

更改原因

此功能自动在预渲染的页面之间共享载荷 数据。这可以在预渲染使用 useAsyncData 或 useFetch 并在不同页面中获取相同数据的网站时显著提高性能。

例如，如果您的网站要求在每一页都进行 useFetch 调用（例如，获取菜单的导航数据或从 CMS 获取网站设置），那么该数据只会在预渲染第一次使用它的页面时获取一次，然后缓存以在预渲染其他页面时使用。

迁移步骤

确保您的任何唯一数据键始终可以解析到相同的数据。例如，如果您正在使用 useAsyncData 获取与特定页面相关的数据，则应提供一个唯一匹配该数据的键。(useFetch 应该会自动为您执行此操作。）

app/pages/test/[slug].vue
// 这在动态页面中是不安全的（例如 `[slug].vue`），因为路由 slug 会影响获取的数据，
// 但 Nuxt 无法知道，因为它在键中没有反映。
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// 相反，您应该使用一个唯一标识获取的数据的键。
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})

或者，您可以通过以下方式禁用此功能：

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
sharedPrerenderData
: false
  }
})

useAsyncData 和 useFetch 中的默认 data 和 error 值

🚦 影响程度：最小

变化内容

useAsyncData 返回的 data 和 error 对象现在默认为 undefined。

更改原因

之前 data 初始化为 null，但在 clearNuxtData 中重置为 undefined。error 初始化为 null。此更改旨在带来更大的一致性。

迁移步骤

如果您正在检查 data.value 或 error.value 是否为 null，可以将这些检查更新为检查 undefined。

您可以通过运行 npx codemod@latest nuxt/4/default-data-error-value 来自动化此步骤。

如果遇到任何问题，您可以通过以下方式恢复先前的行为：

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
defaults
: {
      
useAsyncData
: {
        
value
: 'null',
        
errorValue
: 'null'
      }
    }
  }
})

如果您这样做，请报告一个问题，因为我们不计划将其设置为可配置。

移除在 useAsyncData 和 useFetch 中调用 refresh 时弃用的 boolean 型值

🚦 影响程度：最小

变化内容

之前可以传递 dedupe: boolean 给 refresh。这些是 cancel（true）和 defer（false）的别名。

app.vue
const { 
refresh
 } = await 
useAsyncData
(async () => ({ 
message
: 'Hello, Nuxt 3!' }))

async function 
refreshData
 () {
  await 
refresh
({ dedupe: true })

Type 'true' is not assignable to type 'DedupeOption'.
}
更改原因

这些别名已被移除，以增强清晰度。

问题出现在将 dedupe 作为选项添加到 useAsyncData 时，我们移除了布尔值，因为它们最终变成了_相反_。

refresh({ dedupe: false }) 表示“不要_取消_现有请求以优先考虑此新请求”。但在 useAsyncData 的选项中传递 dedupe: true 意味着“不对现有的挂起请求发起任何新请求”。（见 PR）。

迁移步骤

迁移应该很简单：

  const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt 3!' }))
  
  async function refreshData () {
-   await refresh({ dedupe: true })
+   await refresh({ dedupe: 'cancel' })

-   await refresh({ dedupe: false })
+   await refresh({ dedupe: 'defer' })
  }
您可以通过运行 npx codemod@latest nuxt/4/deprecated-dedupe-value 来自动化此步骤。

在 useAsyncData 和 useFetch 中清除 data 时尊重默认值

🚦 影响程度：最小

变化内容

如果您为 useAsyncData 提供了自定义的 default 值，那么在调用 clear 或 clearNuxtData 时将使用该值，并将被重置为其默认值，而不是简单地取消设置。

更改原因

通常用户会设置一个适当的空值，例如空数组，以避免在迭代时检查 null/undefined。在重置/清除数据时应予以尊重。

迁移步骤

如果遇到任何问题，您可以通过以下方式恢复到先前的行为：

nuxt.config.ts
export default 
defineNuxtConfig
({
  
experimental
: {
    
resetAsyncDataToUndefined
: true,
  }
})

如果您这样做，请报告一个问题，因为我们不计划将其保持为可配置。

useAsyncData 和 useFetch 中的浅层数据反应性

🚦 影响程度：最小

从 useAsyncData、useFetch、useLazyAsyncData 和 useLazyFetch 返回的 data 对象现在是 shallowRef 而不是 ref。

变化内容

当获取新数据时，任何依赖于 data 的内容仍然是响应式的，因为整个对象被替换。但是，如果您的代码更改了该数据结构中的某个属性，则不会触发应用程序中的任何反应性。

更改原因

这为深层嵌套对象和数组带来了 显著 的性能提升，因为 Vue 不需要监视每个属性/数组的修改。在大多数情况下，data 也应该是不可变的。

迁移步骤

在大多数情况下，不需要迁移步骤，但如果您依赖于数据对象的反应性，则有两个选项：

  1. 您可以逐项选择加入每个可组合的深层反应性： 
    - const { data } = useFetch('/api/test')
+ const { data } = useFetch('/api/test', { deep: true })
  2. 您可以更改项目级别的默认行为（不推荐）：
    nuxt.config.ts
    export default 
    defineNuxtConfig
    ({
      
    experimental
    : {
        
    defaults
    : {
          
    useAsyncData
    : {
            
    deep
    : true
          }
    }
  }
})
如果需要，您可以通过运行 npx codemod@latest nuxt/4/shallow-function-reactivity 来自动化此步骤。

builder:watch 中的绝对观察路径

🚦 影响程度：最小

变化内容

Nuxt 的 builder:watch 钩子现在发出一个绝对路径，而不是相对于您的项目 srcDir 的路径。

更改原因

这使我们能够支持观察位于您 srcDir 之外的路径，并为层和其他更复杂的模式提供更好的支持。

迁移步骤

我们已主动迁移了我们知道使用此钩子的公共 Nuxt 模块。请参见 问题 #25339。

但是，如果您是使用 builder:watch 钩子的模块作者，并希望保持向后/向前兼容，可以使用以下代码确保您的代码在 Nuxt v3 和 Nuxt v4 中的工作方式相同：

+ import { relative, resolve } from 'node:fs'
  // ...
  nuxt.hook('builder:watch', async (event, path) => {
+   path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
    // ...
  })
您可以通过运行 npx codemod@latest nuxt/4/absolute-watch-path 来自动化此步骤。

移除 window.__NUXT__ 对象

变化内容

我们正在移除全局 window.__NUXT__ 对象，在应用程序完成水合后。

更改原因

这为多应用模式铺平了道路（#21635），并使我们能够专注于访问 Nuxt 应用程序数据的单一方式 - useNuxtApp()。

迁移步骤

数据仍然可用，但可以使用 useNuxtApp().payload 进行访问：

- console.log(window.__NUXT__)
+ console.log(useNuxtApp().payload)

目录索引扫描

🚦 影响程度：中等

变化内容

您的 middleware/ 文件夹中的子文件夹也会扫描 index 文件，这些文件现在也在您的项目中注册为中间件。

更改原因

Nuxt 自动扫描多个文件夹，包括 middleware/ 和 plugins/。

我们希望在扫描的目录之间保持此行为的一致性，因此文件夹中的子文件夹也扫描以查找 index 文件。

迁移步骤

可能不需要迁移，但如果您希望恢复到之前的行为，您可以添加一个钩子来过滤掉这些中间件：

export default defineNuxtConfig({
  hooks: {
    'app:resolve'(app) {
      app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
    }
  }
})

模板编译更改

🚦 影响程度：最小

变化内容

之前，Nuxt 使用 lodash/template 通过文件系统中的 .ejs 文件格式/语法编译模板。

此外，我们提供了一些模板工具（serialize、importName、importSources），这些工具可用于在这些模板中进行代码生成，现在将被移除。

更改原因

在 Nuxt v3 中，我们转向了具有 getContents() 函数的“虚拟”语法，该语法更加灵活和高效。

此外，lodash/template 曾发生过一系列安全问题。这些问题实际上不会影响 Nuxt 项目，因为它在构建时而不是运行时使用，并且由受信任的代码使用。然而，它们仍出现在安全审计中。此外，lodash 是一个庞大的依赖项，且大多数项目未使用它。

最后，直接在 Nuxt 中提供代码序列化功能并不理想。相反，我们维护类似于 unjs/knitwork 的项目，该项目可以作为您项目的依赖项，并且安全问题可以直接报告/解决，而无需升级 Nuxt 本身。

迁移步骤

我们已提出 PR 更新使用 EJS 语法的模块，但如果您需要自己执行此操作，您有三种向后/向前兼容的替代方案：

+ import { readFileSync } from 'node:fs'
+ import { template } from 'lodash-es'
  // ...
  addTemplate({
    fileName: 'appinsights-vue.js'
    options: { /* some options */ },
-   src: resolver.resolve('./runtime/plugin.ejs'),
+   getContents({ options }) {
+     const contents = readFileSync(resolver.resolve('./runtime/plugin.ejs'), 'utf-8')
+     return template(contents)({ options })
+   },
  })

最后，如果您在使用模板工具（serialize、importName、importSources），您可以用 knitwork 中的工具进行替代：

import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'

const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"{(.+)}"(?=,?$)/gm, r => JSON.parse(r).replace(/^{(.*)}$/, '$1'))

const importSources = (sources: string | string[], { lazy = false } = {}) => {
  return toArray(sources).map((src) => {
    if (lazy) {
      return `const ${genSafeVariableName(src)} = ${genDynamicImport(src, { comment: `webpackChunkName: ${JSON.stringify(src)}` })}`
    }
    return genImport(src, genSafeVariableName(src))
  }).join('\n')
}

const importName = genSafeVariableName
您可以通过运行 npx codemod@latest nuxt/4/template-compilation-changes 来自动化此步骤。

移除实验性功能

🚦 影响程度：最小

变化内容

四个实验性功能在 Nuxt 4 中不再可配置：

  • experimental.treeshakeClientOnly 将为 true（自 v3.0 起默认设置）
  • experimental.configSchema 将为 true（自 v3.3 起默认设置）
  • experimental.polyfillVueUseHead 将为 false（自 v3.4 起默认设置）
  • experimental.respectNoSSRHeader 将为 false（自 v3.4 起默认设置）
  • vite.devBundler 不再可配置 - 默认使用 vite-node
更改原因

这些选项已经保持当前值一段时间，我们没有理由认为它们需要保持可配置。

迁移步骤
  • polyfillVueUseHead 可以通过 该插件 在用户环境中实现。
  • respectNoSSRHeader可以通过 server middleware 在用户环境中实现。

Nuxt 2 与 Nuxt 3+

在下面的表格中，快速比较了 Nuxt 的 3 个版本：

特性 / 版本Nuxt 2Nuxt BridgeNuxt 3+
Vue223
稳定性😊 稳定😊 稳定😊 稳定
性能🏎 快✈️ 更快🚀 最快
Nitro 引擎❌✅✅
ESM 支持🌙 部分👍 更好✅
TypeScript☑️ 选择性🚧 部分✅
组合 API❌🚧 部分✅
选项 API✅✅✅
组件自动导入✅✅✅
<script setup> 语法❌🚧 部分✅
自动导入❌✅✅
webpack445
Vite⚠️ 部分🚧 部分✅
Nuxi CLI❌ 旧✅ nuxi✅ nuxi
静态网站✅✅✅

从 Nuxt 2 迁移到 Nuxt 3+

迁移指南提供了 Nuxt 2 功能与 Nuxt 3+ 功能的逐步比较，以及帮助您调整当前应用程序的建议。

查看 从 Nuxt 2 迁移到 Nuxt 3 的指南。

从 Nuxt 2 迁移到 Nuxt Bridge

如果您希望逐步迁移您的 Nuxt 2 应用程序到 Nuxt 3，可以使用 Nuxt Bridge。Nuxt Bridge 是一个兼容层，允许您在 Nuxt 2 中使用 Nuxt 3+ 的功能，采用选择性机制。

从 Nuxt 2 迁移到 Nuxt Bridge

测试工具

如何测试你的 Nuxt 应用程序。

自动导入

Nuxt 自动导入应用程序中使用的组件、组合器和 Vue.js API，无需显式导入。