v4 (4.0.0)
GitHub

升级指南

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

升级 Nuxt

最新版本

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

npx nuxt upgrade

夜间版本通道

要使用最新的 Nuxt 构建并在发布之前测试功能，请阅读 夜间版本通道 指南。

迁移到 Nuxt 4

Nuxt 4 包含显著的改进和变化。本指南将帮助您将现有的 Nuxt 3 应用程序迁移到 Nuxt 4。

首先，升级到 Nuxt 4：

npm install nuxt@^4.0.0

升级后，大多数 Nuxt 4 的行为现在是默认设置。然而，如果您在迁移过程中需要保持向后兼容性，某些功能仍然可以进行配置。

以下部分详细说明了升级到 Nuxt 4 时所需的关键更改和迁移。

下面记录了重大或显著的更改，以及迁移步骤和可用的配置选项。

使用 Codemods 迁移

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

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

有关 Nuxt 4 codemods 的完整列表、每个 codemod 的详细信息、其来源和多种执行方式，请访问 Codemod Registry。

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

npx codemod@latest nuxt/4/migration-recipe

此命令将按顺序执行所有 codemods，并可选择取消选择任何您不希望运行的项目。每个 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/
shared/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts
With this new structure, the ~ alias now points to the app/ directory by default (your srcDir). This means ~/components resolves to app/components/, ~/pages to app/pages/, etc.

👉 更多详情请参见 实现此变更的 PR。

变更原因

  1. 性能 - 将所有代码放在代码库的根目录中，会导致 .git/ 和 node_modules/ 文件夹被文件系统监视器扫描/包含，这可能显著延迟非 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: '.',
  // 这指定 `router.options.ts` 和 `spa-loading-template.html` 的目录前缀
  dir: {
    app: 'app'
  }
})

单例数据获取层

🚦 影响级别：适中

变更内容

Nuxt 的数据获取系统（useAsyncData 和 useFetch）已被显著重组，以提高性能和一致性：

  1. 同键共享 ref：对同一键的所有 useAsyncData 或 useFetch 调用现在共享同一 data、error 和 status refs。这意味着所有具有显式键的调用不得有冲突的 deep、transform、pick、getCachedData 或 default 选项。
  2. 更好地控制 getCachedData：每次获取数据时，都会调用 getCachedData 函数，即使这被观察者引起或调用 refreshNuxtData 也会如此。（以前，在这些情况下总是会获取新数据，而且不会调用此函数。）为了允许更好地控制何时使用缓存数据以及何时重新获取，函数现在接收一个上下文对象，包含请求的原因。
  3. 支持反应性键：您现在可以使用计算的 refs、普通的 refs 或 getter 函数作为键，这样可以实现自动重新获取数据（并单独存储数据）。
  4. 数据清理：当最后一个使用 useAsyncData 获取数据的组件被卸载时，Nuxt 将删除该数据，以避免不断增长的内存使用。

变更原因

这些更改旨在改善内存使用，并在对 useAsyncData 的调用之间提高加载状态的一致性。

迁移步骤

  1. 检查不一致的选项：审核任何使用相同键但选项或获取函数不同的组件。
    // 这现在将触发警告
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

    将共享显式键（并且有自定义选项）的任何 useAsyncData 调用提取到它们自己的组合中可能是有益的：
    composables/useUserData.ts
    export function useUserData(userId: string) {
  return useAsyncData(
    `user-${userId}`,
    () => fetchUser(userId),
    { 
      deep: true,
      transform: (user) => ({ ...user, lastAccessed: new Date() })
    }
  )
}
  2. 更新 getCachedData 实现：
    useAsyncData('key', fetchFunction, {
-  getCachedData: (key, nuxtApp) => {
-    return cachedData[key]
-  }
+  getCachedData: (key, nuxtApp, ctx) => {
+    // ctx.cause - 可以是 'initial' | 'refresh:hook' | 'refresh:manual' | 'watch'
+    
+    // 示例：在手动刷新时不使用缓存
+    if (ctx.cause === 'refresh:manual') return undefined
+    
+    return cachedData[key]
+  }
})

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

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
    purgeCachedData: false
  }
})

修正了层中的模块加载顺序

🚦 影响级别：最小

变更内容

使用 Nuxt layers 时，模块加载的顺序已被修正。以前，项目根目录中的模块在扩展层中的模块之前加载，这与预期的行为相反。

现在模块以正确的顺序加载：

  1. 首先是层模块（按扩展顺序 - 深层模块优先）
  2. 最后是项目模块（优先级最高）

这影响到：

  • 在 nuxt.config.ts 中的 modules 数组定义的模块
  • 从 modules/ 目录自动发现的模块

变更原因

此更改确保：

  • 扩展层的优先级低于消费项目
  • 模块执行顺序与直观的层继承模式相匹配
  • 模块配置和钩子在多层设置中按预期工作

迁移步骤

大多数项目不需要更改，因为这修正了加载顺序以匹配预期行为。

但是，如果您的项目依赖于先前不正确的顺序，则可能需要：

  1. 审查模块依赖关系：检查是否有任何模块依赖于特定的加载顺序
  2. 调整模块配置：如果模块被配置为解决不正确的顺序
  3. 彻底测试：确保所有功能在更正的顺序下按预期工作

新正确顺序的示例：

// Layer: my-layer/nuxt.config.ts
export default defineNuxtConfig({
  modules: ['layer-module-1', 'layer-module-2']
})

// Project: nuxt.config.ts
export default defineNuxtConfig({
  extends: ['./my-layer'],
  modules: ['project-module-1', 'project-module-2']
})

// Loading order (corrected):
// 1. layer-module-1
// 2. layer-module-2  
// 3. project-module-1 (can override layer modules)
// 4. project-module-2 (can override layer modules)

如果您遇到由于需要注册钩子而导致的模块顺序依赖问题，请考虑使用 modules:done 钩子 来处理需要调用钩子的模块。该钩子在所有其他模块加载后运行，这意味着使用它是安全的。

👉 请参见 PR #31507 和 issue #25719 以获取更多详细信息。

路由元数据的去重

🚦 影响级别：最小

变更内容

现在可以使用 definePageMeta 设置一些路由元数据，例如 name、path 等。以前，这些在路由和路由元数据上都可用（例如，route.name 和 route.meta.name）。

现在，它们只能在路由对象上访问。

变更原因

这是默认启用 experimental.scanPageMeta 的结果，是一种性能优化。

迁移步骤

此迁移应该是直接的：

  const route = useRoute()
  
- console.log(route.meta.name)
+ console.log(route.name)

规范化组件名称

🚦 影响级别：适中

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
  }
})

Unhead v2

🚦 影响级别：最小

变更内容

用于生成 <head> 标签的 Unhead 已更新至版本 2。虽然基本兼容，但它包括多个底层 API 的重大变更。

  • 移除了属性：vmid、hid、children、body。
  • 不再支持 Promise 输入。
  • 现在使用 Capo.js 默认对标签进行排序。

迁移步骤

上述更改对您的应用应有最小影响。

如果您遇到问题，请检查：

  • 您没有使用任何已移除的属性。
useHead({
  meta: [{ 
    name: 'description', 
    // meta 标签不需要 vmid 或键    
-   vmid: 'description' 
-   hid: 'description'
  }]
})

import { TemplateParamsPlugin, AliasSortingPlugin } from '@unhead/vue/plugins'

export default defineNuxtPlugin({
  setup() {
    const unhead = injectHead()
    unhead.use(TemplateParamsPlugin)
    unhead.use(AliasSortingPlugin)
  }
})

虽然不是必需的，但建议将任何来自 @unhead/vue 的导入更新为 #imports 或 nuxt/app。

-import { useHead } from '@unhead/vue'
+import { useHead } from '#imports'

如果您仍然遇到问题，您可以通过启用 head.legacy 配置恢复到 v1 行为。

export default defineNuxtConfig({
  unhead: {
    legacy: true,
  }
})

SPA 加载屏幕的新 DOM 位置

🚦 影响级别：最小

变更内容

在呈现仅客户端页面（ssr: false）时，我们可选择在 Nuxt 应用根中渲染加载屏幕（来自 ~/app/spa-loading-template.html - note that this has also changed to ~/spa-loading-template.html in Nuxt 4）：

<div id="__nuxt">
  <!-- spa loading template -->
</div>

现在，我们默认为在 Nuxt 应用根旁边渲染模板：

<div id="__nuxt"></div>
<!-- spa loading template -->

变更原因

这样可以使 spa 加载模板在 Vue 应用 suspense 解析之前保持在 DOM 中，防止出现白屏闪烁。

迁移步骤

如果您使用 CSS 或 document.queryElement 针对 SPA 加载模板进行定向，您将需要更新选择器。为此，您可以使用新的 app.spaLoaderTag 和 app.spaLoaderAttrs 配置选项。

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

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    spaLoadingTemplateLocation: 'within',
  }
})

解析的 error.data

🚦 影响级别：最小

可以通过 data 属性抛出错误，但这未被解析。现在，它被解析并可在 error 对象中访问。尽管这是一个修复，但如果您依赖之前的行为并手动解析，这在技术上是一个破坏性更改。

迁移步骤

更新您的自定义 error.vue，以去除对 error.data 的任何额外解析：

  <script setup lang="ts">
  import type { NuxtError } from '#app'

  const props = defineProps({
    error: Object as () => NuxtError
  })

- const data = JSON.parse(error.data)
+ const data = error.data
  </script>

更细粒度的内联样式

🚦 影响级别：适中

Nuxt 现在只会为 Vue 组件内联样式，而不是全局 CSS。

变更内容

以前，Nuxt 会内联所有 CSS，包括全局样式，并删除指向单独 CSS 文件的 <link> 元素。现在，Nuxt 只会对 Vue 组件执行此操作（此前会生成独立的 CSS 块）。我们认为这是减少单独网络请求的更好平衡（正如以往，对于初始加载，每个页面或每个组件将不再有单独请求 .css 文件），并允许对单个全局 CSS 文件进行缓存，减少初始请求的文档下载大小。

迁移步骤

此功能是完全可配置的，您可以通过设置 inlineStyles: true 将全局 CSS 以及每个组件 CSS 内联，以恢复到之前的行为。

nuxt.config.ts
export default defineNuxtConfig({
  features: {
    inlineStyles: true
  }
})

在解析后扫描页面元数据

🚦 影响级别：最小

变更内容

我们现在在调用 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 选项

🚦 影响级别：最小

变更内容

以前可以将 dedupe: boolean 传递给 refresh。这些是 cancel (true) 和 defer (false) 的别名。

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

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

变更原因

这些别名被移除，以提高清晰度。

当向 useAsyncData 添加 dedupe 选项时出现了此问题，我们删除了布尔值，因为它们最终成为 反义。

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。在重置/清除数据时应尊重这一点。

useAsyncData 和 useFetch 中 pending 值的对齐

🚦 影响级别：中等

从 useAsyncData、useFetch、useLazyAsyncData 和 useLazyFetch 返回的 pending 对象现在是一个计算属性，只有在 status 也处于待处理状态时才为 true。

变更内容

现在，当传入 immediate: false 时，pending 将在第一次请求发出之前为 false。这与之前的行为不同，之前 pending 在第一次请求发出之前始终为 true。

变更原因

这使得 pending 的含义与 status 属性对齐，当请求正在进行时，status 也为 pending。

迁移步骤

如果您依赖于 pending 属性，请确保您的逻辑考虑到新的行为，即 pending 仅在状态也为待处理时才为 true。

  <template>
-   <div v-if="!pending">
+   <div v-if="status === 'success'">
      <p>Data: {{ data }}</p>
    </div>
    <div v-else>
      <p>Loading...</p>
    </div>
  </template>
  <script setup lang="ts">
  const { data, pending, execute, status } = await useAsyncData(() => fetch('/api/data'), {
    immediate: false
  })
  onMounted(() => execute())
  </script>

或者，您可以暂时恢复到之前的行为：

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

useAsyncData 和 useFetch 中的关键更改行为

🚦 影响级别：中等

变更内容

在 useAsyncData 或 useFetch 中使用反应性键时，Nuxt 在键更改时会自动重新获取数据。当设置 immediate: false 时，useAsyncData 仅在数据已经获取过一次时才会在键更改时获取数据。

之前，useFetch 的行为略有不同。它在键更改时总是会获取数据。

现在，useFetch 和 useAsyncData 的行为一致——仅在键更改时获取数据，如果数据已经获取过一次。

变更原因

这确保了 useAsyncData 和 useFetch 之间的一致行为，避免了意外获取。如果您设置了 immediate: false，那么您必须手动触发 refresh 或 execute，否则数据在 useFetch 或 useAsyncData 中将从未被获取。

迁移步骤

此更改应总体上提高预期行为，但如果您期望更改一个非立即的 useFetch 的键或选项，现在您需要在第一次手动触发它。

  const id = ref('123')
  const { data, execute } = await useFetch('/api/test', {
    query: { id },
    immediate: false
  )
+ watch(id, () => execute(), { once: true })

如果您希望退出此行为：

// 或在您的 Nuxt 配置中全局设置
export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: 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 模块。请参阅 issue #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/。

我们希望在扫描目录之间保持这种行为一致，因此在 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 语法的模块，但如果您需要自己执行此操作，您有三个向后/向前兼容的替代方案：

  • 将字符串插值逻辑直接移动到 getContents() 中。
  • 使用自定义函数进行替换，例如在 https://github.com/nuxt-modules/color-mode/pull/240 中。
  • 在您的项目中将 es-toolkit/compat 作为依赖项使用（这是 lodash 模板的替代品）：
+ import { readFileSync } from 'node:fs'
+ import { template } from 'es-toolkit/compat'
  // ...
  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 自动化此步骤

默认 TypeScript 配置更改

🚦 影响级别：最小

变更内容

compilerOptions.noUncheckedIndexedAccess 现在是 true 而不是 false。

变更原因

此更改是对先前 3.12 配置更新 的后续，主要遵循 TotalTypeScript 的建议。

迁移步骤

有两种方法：

  1. 在您的应用程序上运行类型检查并修复任何新错误（推荐）。
  2. 在您的 nuxt.config.ts 中覆盖新默认值：
    export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        noUncheckedIndexedAccess: false
      }
    }
  }
})

TypeScript 配置拆分

🚦 影响级别：最小

变更内容

Nuxt 现在为不同的上下文生成独立的 TypeScript 配置，以提供更好的类型检查体验：

  1. 新的 TypeScript 配置文件：Nuxt 现在生成额外的 TypeScript 配置：
    • .nuxt/tsconfig.app.json - 用于您的应用程序代码（Vue 组件、组合式等）
    • .nuxt/tsconfig.server.json - 用于您的服务器端代码（Nitro/server 目录）
    • .nuxt/tsconfig.node.json - 用于您的构建时代码（模块、nuxt.config.ts 等）
    • .nuxt/tsconfig.shared.json - 用于应用程序和服务器上下文之间共享的代码（如类型和非环境特定实用程序）
    • .nuxt/tsconfig.json - 旧版配置，以保持向后兼容性
  2. 向后兼容性：扩展 .nuxt/tsconfig.json 的现有项目将继续按以前的方式工作。
  3. 选择性项目引用：新项目或希望获得更好类型检查的项目可以采用 TypeScript 的项目引用功能。
  4. 特定上下文的类型检查：每个上下文现在都有适当的编译器选项和包含/排除特定环境的设置。
  5. 新的 typescript.nodeTsConfig 选项：您现在可以自定义 Node.js 构建时代码的 TypeScript 配置。

变更原因

此更改提供了几个好处：

  1. 更好的类型安全：每个上下文（应用程序、服务器、构建时）都获得了适当的类型检查，具有特定于上下文的全局变量和 API。
  2. 改进的 IDE 体验：为代码库的不同部分提供更好的 IntelliSense 和错误报告。
  3. 更清晰的分离：服务器代码不会错误地建议客户端 API，反之亦然。
  4. 性能：TypeScript 可以更有效地检查具有适当作用域配置的代码。

例如，自动导入在您的 nuxt.config.ts 中不可用（但以前这并未被 TypeScript 标记）。虽然 IDE 识别了 server/ 目录中 tsconfig.json 提示的单独上下文，但这并未反映在类型检查中（需要单独的步骤）。

迁移步骤

不需要迁移 - 现有项目将继续按以前的方式工作。

但是，为了利用改进的类型检查，您可以选择采用新的项目引用方法：

  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. 删除任何手动的服务器 tsconfig.json 文件（如 server/tsconfig.json），这些文件扩展了 .nuxt/tsconfig.server.json。
  3. 更新您的类型检查脚本 以使用项目引用的构建标志：
    - "typecheck": "nuxt prepare && vue-tsc --noEmit"
+ "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
  4. 如果需要，配置 Node.js TypeScript 选项：
    export default defineNuxtConfig({
  typescript: {
    // Customize app/server TypeScript config
    tsConfig: {
      compilerOptions: {
        strict: true
      }
    },
    // Customize build-time TypeScript config  
    nodeTsConfig: {
      compilerOptions: {
        strict: true
      }
    }
  }
})
  5. 更新任何运行 TypeScript 检查的 CI/构建脚本，以确保它们使用新的项目引用方法。

新的配置为选择加入的项目提供了更好的类型安全性和智能感知，同时保持对现有设置的完全向后兼容。

移除实验性功能

🚦 影响级别：最小

变化内容

在 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 可以通过 服务器中间件 在用户空间实现。

移除顶级 generate 配置

🚦 影响级别：最小

变更内容

顶级的 generate 配置选项在 Nuxt 4 中不再可用。这包括它的所有属性：

  • generate.exclude - 用于排除不进行预渲染的路由
  • generate.routes - 用于指定要预渲染的路由

变更原因

顶级的 generate 配置是 Nuxt 2 的遗留部分。我们已经支持 nitro.prerender 一段时间了，它是 Nuxt 3+ 中配置预渲染的首选方式。

迁移步骤

用相应的 nitro.prerender 选项替换 generate 配置：

export default defineNuxtConfig({
- generate: {
-   exclude: ['/admin', '/private'],
-   routes: ['/sitemap.xml', '/robots.txt']
- }
+ nitro: {
+   prerender: {
+     ignore: ['/admin', '/private'],
+     routes: ['/sitemap.xml', '/robots.txt']
+   }
+ }
})
了解更多关于 Nitro 的预渲染配置选项。

Nuxt 2 与 Nuxt 3+

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

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

从 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