v3.16
GitHub

升级指南

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

升级 Nuxt

最新版本

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

npx nuxi upgrade

夜间版本通道

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

夜间版本通道的 latest 标签目前正在跟踪 Nuxt v4 分支，这意味着它目前有更高的可能性会出现重大变更——请小心！您可以通过 "nuxt": "npm:nuxt-nightly@3x" 选择加入 3.x 分支的夜间版本发布。

测试 Nuxt 4

Nuxt 4 的发布日期 待发布。它取决于在 Nitro 的主要版本发布后，社区有足够的时间进行正确的测试。您可以在 此 PR 中跟踪 Nitro 发布的进展。

在此发布之前，可以测试 Nuxt 4 从 Nuxt 版本 3.12+ 的许多重大变更。

选择加入 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,
  //   spaLoadingTemplateLocation: 'within',
  //   parseErrorData: false,
  //   defaults: {
  //     useAsyncData: {
  //       deep: true
  //     }
  //   }
  // },
  // features: {
  //   inlineStyles: true
  // },
  // unhead: {
  //   renderSSRHeadOptions: {
  //     omitLineBreaks: false
  //   }
  // }
})
目前，您需要在每一层中定义选择加入 Nuxt 4 行为的兼容性版本。在 Nuxt 4 发布后，这将不再需要。

当您将 compatibilityVersion 设置为 4 时，您的 Nuxt 配置中的默认值将更改为选择加入 Nuxt v4 行为，但您可以在测试时逐项重新启用 Nuxt v3 行为，请参考上面的注释行。如果出现任何问题，请提交问题，以便我们可以在 Nuxt 或生态系统中进行解决。

重大的或重要的变更将在此处注明，并附上向后/向前兼容的迁移步骤。

在最终发布之前，本节内容可能会发生变更，因此如果您使用 compatibilityVersion: 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/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts

👉 更多详情请参见 实现此变更的 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: '.',
  // 这指定 `app/router.options.ts` 和 `app/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
  }
})

路由元数据的去重

🚦 影响级别：最小

变更内容

现在可以使用 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）：

<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.config.ts
export default defineNuxtConfig({
  experimental: {
    parseErrorData: false
  },
})

更细粒度的内联样式

🚦 影响级别：适中

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

迁移步骤

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

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 模块。请参阅 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 自动化此步骤

移除实验性功能

🚦 影响级别：最小

变更内容

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

Nuxt 2 与 Nuxt 3+

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

特性 / 版本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