升级指南

升级 Nuxt

最新版本

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

npx nuxt upgrade

yarn nuxt upgrade

pnpm nuxt upgrade

bun x nuxt upgrade

deno x nuxt upgrade

夜版发布渠道

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

测试 Nuxt 5

Nuxt 5 目前正在开发中。从 Nuxt 4.2+ 开始，你可以通过将 future.compatibilityVersion 设置为 5 来测试它的许多破坏性变更：

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5,
  },
})

随后，Nuxt 配置中的各项默认值会发生变化，以选择启用 Nuxt 5 行为。在 Nuxt 4 中，这包括：

• Vite Environment API：启用 experimental.viteEnvironmentApi，改变 Vite 插件的注册和配置方式
• 区分大小写的路由：页面路由会严格匹配 URL 的大小写，与 Nitro 保持一致，因此 /About 不再匹配 pages/about.vue
• 规范化的页面名称：页面组件名称与路由名称保持一致，确保 <KeepAlive> 行为一致
• 可序列化的页面 meta：experimental.extractSerializablePageMeta 会在构建时提取可静态分析的 definePageMeta 值
• 客户端负载提取：experimental.payloadExtraction 会变为 'client'，将负载内联到预渲染页面的 HTML 中
• clearNuxtState 重置为默认值：clearNuxtState 会将状态重置为 useState 的初始值，而不是将其设为 undefined
• 非异步的 callHook：callHook 可能返回 void，而不再总是返回 Promise
• navigateTo 提前返回：experimental.navigateToEarlyReturn 会阻止中间件在重定向后继续执行
• 仅限服务器端的 head 组合式函数：useServerHead、useServerHeadSafe 和 useServerSeoMeta 不再自动导入，unhead.legacy 会被忽略，Unhead 的旧版插件不再注册，并且始终启用 Capo 排序
• 默认关闭 PostCSS：除非你在 postcss.plugins 中启用 autoprefixer 和 cssnano，否则不会再配置它们
• 带键的组合式函数需要 source：没有字符串 source 的 optimization.keyedComposables 条目，不再通过其自动导入项进行匹配
• 注释节点占位符：仅客户端组件使用注释节点而不是 <div>作为 SSR 占位符
• 类型化页面：启用 experimental.typedPages，以支持经过类型检查的路由
• 错误响应格式：启用 experimental.inlineErrorRendering，因此页面错误会返回错误页面，服务器路由错误会返回 JSON，且不受请求标头影响
• 类型化 $fetch：experimental.routeTypedFetch 会根据生成的路由类型为 $fetch 和 useFetch 提供类型
• 关闭 Nitro 自动导入：服务器代码会显式导入辅助函数，例如从 nuxt/server 导入，而不是依赖自动导入兼容层。设置 experimental.nitroAutoImports: true 可继续使用自动导入
• 禁用 Vue Options API：Options API 会从客户端包中编译移除，以减小其体积
• 更严格的副作用导入检查：生成的 tsconfig.json 会启用 noUncheckedSideEffectImports
• 忽略 TypeScript baseUrl：生成的 TypeScript 配置不再使用 compilerOptions.baseUrl 解析 Nuxt 别名

每项变更的迁移步骤，以及此次升级带来的其他所有内容，都记录在 Nuxt 5 升级指南中。

迁移到 nuxt/server

从 Nuxt 4.6 开始，服务器代码可以从 nuxt/server 而不是 h3 导入处理程序和辅助函数，因此同一个文件可以在 Nuxt 4（nitropack v2 和 h3 v1）以及 Nuxt 5（Nitro v3 和 h3 v2）上运行。

在 Nuxt 4.6 中，请从 nuxt/server 显式导入 defineEventHandler 和辅助函数。同名的自动导入项属于 h3 v1，而 h3 的 defineEventHandler 传递给处理程序的事件，与 nuxt/server 辅助函数读取的事件不同。

+ import { defineEventHandler, getQuery } from 'nuxt/server'
+
 export default defineEventHandler((event) => {
   const { name } = getQuery<{ name?: string }>(event)
   return { message: `Hello, ${name ?? 'world'}!` }
 })

在 Nuxt 5 中，这些同名项会从 nuxt/server 自动导入，因此在 Nuxt 4.6 中编写的显式导入可以继续原样使用。

与 h3 v1 的差异

nuxt/server 之外的辅助函数

对于需要使用 nuxt/server 未提供的 h3 或 Nitro 辅助函数（例如 readMultipartFormData、proxyRequest、useStorage 或 defineCachedEventHandler）的处理程序，请继续从 h3（或 nitropack/runtime）为该处理程序导入 defineEventHandler 和这些辅助函数。这样编写的代码与服务器运行时绑定，需要在 Nuxt 5 中重新检查。

import { defineEventHandler, readMultipartFormData } from 'h3'

export default defineEventHandler(async (event) => {
  const parts = await readMultipartFormData(event)
  return { received: parts?.length ?? 0 }
})

NUXT_E8012

当 nuxt/server 的辅助函数（例如 readValidatedBody、getValidatedQuery、handleCors 或 useSession）收到 h3 事件时，请求会失败并返回一条以 [NUXT_E8012] 开头的 500 错误消息。这意味着该处理程序是用 h3 的 defineEventHandler 定义的（通常是自动导入的那个）。请在与辅助函数相同的文件中从 nuxt/server 导入 defineEventHandler。

应用密钥

nuxt/server 的会话辅助函数和 deriveSecret 会读取 runtimeConfig.appSecret，你可以通过 NUXT_APP_SECRET 设置该值。在 Nuxt 4 中，nitropack v2 会解析环境变量覆盖值，因此仅由数字组成的密钥会被解析为数字；请参阅应用密钥，了解如何避免此问题。

迁移到 Nuxt 4

Nuxt 4 包含了重要的改进和变更。本指南将帮助你将现有的 Nuxt 3 应用迁移到 Nuxt 4。

首先，升级到 Nuxt 4：

npm install nuxt@^4.0.0

yarn add nuxt@^4.0.0

pnpm add nuxt@^4.0.0

bun add nuxt@^4.0.0

deno add npm:nuxt@^4.0.0

升级后，大多数 Nuxt 4 行为现在都是默认行为。不过，如果你在迁移期间需要保持向后兼容，仍然可以配置某些功能。

以下部分详细介绍升级到 Nuxt 4 时的主要变更和所需的迁移步骤。

下文记录了具有破坏性或较为重要的变更，以及相应的迁移步骤和可用的配置选项。

使用 Codemods 迁移

为了简化升级流程，我们与 Codemod 团队合作，使用一些开源 codemod 自动完成了许多迁移步骤。

如需查看 Nuxt 4 codemod 的完整列表、每个 codemod 的详细信息及其源代码，以及多种运行方式，请访问 Codemod Registry。

你可以使用以下 codemod recipe 运行本指南中提到的所有 codemod：

# Angepinnte Version wegen https://github.com/codemod/codemod/issues/1710
npx codemod@0.18.7 nuxt/4/migration-recipe

# Angepinnte Version wegen https://github.com/codemod/codemod/issues/1710
yarn dlx codemod@0.18.7 nuxt/4/migration-recipe

# Angepinnte Version wegen https://github.com/codemod/codemod/issues/1710
pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe

# Angepinnte Version wegen https://github.com/codemod/codemod/issues/1710
bun x codemod@0.18.7 nuxt/4/migration-recipe

# Angepinnte Version wegen https://github.com/codemod/codemod/issues/1710
deno x codemod@0.18.7 nuxt/4/migration-recipe

此命令会依次执行所有 codemod，你可以选择取消不想运行的 codemod。下文也会列出每个 codemod 及其对应的变更，你可以单独运行它们。

新的目录结构

🚦 影响级别：重要

Nuxt 现在默认使用新的目录结构，同时保持向后兼容（因此，如果 Nuxt 检测到你使用的是旧结构，例如顶层的 app/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>/
• 新增了 shared/ 目录，用于 Vue 应用与 Nitro 服务器之间共享代码，并为 shared/utils/ 和 shared/types/ 提供自动导入

.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/
  types/
  utils/
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/、app/layouts/、app/middleware/、app/pages/、app/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/、shared/ 和 server/ 文件夹留在 app/ 文件夹之外，即项目根目录中。
4. 请记得更新任何第三方配置文件，使其适配新的目录结构，例如 tailwindcss 或 eslint 配置（如果需要；@nuxtjs/tailwindcss 应能自动正确配置 tailwindcss）。

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

你也可以通过以下配置强制使用 v3 文件夹结构：

export default defineNuxtConfig({
  // Dies setzt den neuen Standardwert von srcDir von `app` wieder auf dein Stammverzeichnis zurück
  srcDir: '.',
  // Dies legt das Verzeichnispräfix für `router.options.ts` und `spa-loading-template.html` fest
  dir: {
    app: 'app',
  },
})

单例数据获取层

🚦 影响级别：中等

变更内容

Nuxt 的数据获取系统（useAsyncData 和 useFetch）进行了大幅重组，以提升性能和一致性：

1. 相同 key 共享 refs：现在，所有使用相同 key 调用 useAsyncData 或 useFetch 的地方都会共享相同的 data、error 和 status refs。这意味着，所有带有显式 key 的调用都不能使用互相冲突的 deep、transform、pick、getCachedData 或 default 选项。
2. 更灵活地控制 getCachedData：现在每次获取数据时都会调用 getCachedData 函数，即使这是由 watcher 或调用 refreshNuxtData 触发的。（以前在这些情况下总是会获取新数据，而不会调用此函数。）为了更好地控制何时使用缓存数据、何时重新获取数据，该函数现在会收到一个包含请求触发原因的上下文对象。
3. 支持响应式 key：现在可以使用计算 refs、普通 refs 或 getter 函数作为 key，从而支持自动重新获取数据（并单独存储数据）。
4. 数据清理：当最后一个使用 useAsyncData 获取数据的组件卸载时，Nuxt 会移除这些数据，以避免内存持续增长。

变更原因

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

迁移步骤

1. 检查不一致的选项：检查是否有组件使用相同的 key，却指定了不同的选项或获取函数。

   // Dies löst jetzt eine Warnung aus
   const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
   const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

   你可以考虑将共享显式 key（且带有自定义选项）的 useAsyncData 调用提取到它们自己的组合式函数中：

   app/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 - can be 'initial' | 'refresh:hook' | 'refresh:manual' | 'watch'
   +    
   +    // Example: Don't use cache on manual refresh
   +    if (ctx.cause === 'refresh:manual') return undefined
   +    
   +    return cachedData[key]
   +  }
   })

或者，你目前可以通过以下配置禁用此行为：

export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
    purgeCachedData: false,
  },
})

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

🚦 影响级别：最小

变更内容

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

现在，模块会按正确顺序加载：

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'],
})

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

// Ladereihenfolge (korrigiert):
// 1. layer-module-1
// 2. layer-module-2
// 3. project-module-1 (kann Layer-Module überschreiben)
// 4. project-module-2 (kann Layer-Module überschreiben)

如果你因为需要注册钩子而遇到模块顺序依赖问题，请考虑在需要调用钩子的模块中使用 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 中识别该组件，需要使用这个名称。

但 Nuxt 的自动导入会使用 SomeFolderMyComponent 作为名称。

此次变更后，这两个名称将保持一致，Vue 生成的组件名将匹配 Nuxt 的命名模式。

迁移步骤

确保你在使用 @vue/test-utils 的 findComponent 进行测试，以及任何依赖组件名的 <KeepAlive> 中使用更新后的名称。

或者，你现在可以通过以下配置禁用此行为：

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 或 key    
-   vmid: 'description' 
-   hid: 'description'
  }]
})

• 如果你使用了模板参数或别名标签排序，需要显式启用相关插件。

import { AliasSortingPlugin, TemplateParamsPlugin } 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）时，加载屏幕（默认值为 ~/app/spa-loading-template.html；在 Nuxt 4 中改为 ~/spa-loading-template.html）渲染在 Nuxt 应用根节点内：

<div id="__nuxt">
  <!-- SPA-Ladevorlage -->
</div>

现在，加载屏幕默认渲染在 Nuxt 应用根节点旁边：

<div id="__nuxt"></div>
<!-- SPA-Ladevorlage -->

变更原因

这样能确保加载屏幕在 Vue 应用的 Suspense 解析完前一直存在，避免出现闪白。

迁移步骤

如果你曾用 CSS 或 document.querySelector 定位加载屏幕元素，请更新选择器。你可以利用新的 app.spaLoaderTag 和 app.spaLoaderAttrs 配置来辅助定位。

或者，你可以通过以下配置恢复到旧行为：

export default defineNuxtConfig({
  experimental: {
    spaLoadingTemplateLocation: 'within',
  },
})

解析后的 error.data

🚦 影响级别：最小

之前抛出的错误对象中若有 data 属性，未自动解析。现在已自动解析，并可通过错误对象访问。虽然这是一项修复，但如果你依赖旧行为并手动解析，这将属于破坏性变更。

迁移步骤

更新自定义 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>。现在仅对 Vue 组件相关的 CSS 内联（此前这些样式会产生独立的 CSS Chunk）。这能更好地平衡以下目标：减少网络请求数量（首屏加载时不会为每个页面或组件单独请求 .css 文件）、提升全局 CSS 缓存效率，以及减少初始请求体积。

迁移步骤

此特性可通过配置完全控制。你可以通过设置 inlineStyles: true 恢复之前的行为，即对全局 CSS 也进行内联：

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

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

export default defineNuxtConfig({
  experimental: {
    scanPageMeta: true,
  },
})

共享预渲染数据

🚦 影响级别：中等

变更内容

我们启用了一项此前的实验功能，用于在不同页面之间共享 useAsyncData 和 useFetch 调用的数据。详见原始 PR。

变更原因

该功能会自动在预渲染页面之间共享负载中的 数据。当预渲染使用 useAsyncData 或 useFetch，并且在不同页面请求相同数据的站点时，能显著提升性能。

例如，如果你的网站在每个页面都需要调用 useFetch（比如用于获取菜单导航数据，或 CMS 中的站点设定），这些数据会在首次预渲染使用它的页面时只被请求一次，并缓存起来供其他页面的预渲染使用。

迁移步骤

确保你数据的唯一键总是能解析到相同的数据。例如，如果你使用 useAsyncData 请求与特定页面相关的数据，应提供一个唯一匹配该数据的键。（useFetch 会自动为你处理）

// 在动态页面（例如 `[slug].vue`）中，这样使用是不安全的，因为路由的 slug 会影响请求的数据，
// 而 Nuxt 无法感知这一点，因为它未反映在 key 中。
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// 正确做法是使用唯一标识请求数据的 key。
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})

或者，你可以禁用此功能：

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。

移除调用 useAsyncData 和 useFetch 的 refresh 时 dedupe 选项的布尔值支持

🚦 影响级别：最小

变更内容

之前调用 refresh 时可以传递 dedupe: boolean。它们分别是 cancel（true）和 defer（false）的别名。

// @errors: 2322
const { refresh } = await useAsyncData(() => Promise.resolve({ 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' })
  }

- clearNuxtState('myKey')
+ clearNuxtState('myKey', { reset: false })

export default defineNuxtConfig({
  experimental: {
    defaults: {
      useState: {
        resetOnClear: false,
      },
    },
  },
})

export default defineNuxtConfig({
  experimental: {
    defaults: {
      useState: {
        resetOnClear: 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>

export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: true,
  },
})

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

+ import { relative, resolve } from 'node:fs'
  // ...
  nuxt.hook('builder:watch', async (event, path) => {
+   path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
    // ...
  })

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

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

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

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

export default defineNuxtConfig({
- generate: {
-   exclude: ['/admin', '/private'],
-   routes: ['/sitemap.xml', '/robots.txt']
- }
+ nitro: {
+   prerender: {
+     ignore: ['/admin', '/private'],
+     routes: ['/sitemap.xml', '/robots.txt']
+   }
+ }
})

<template>
  <NuxtPage :keepalive="{
-   include: ['index']
+   include: ['foo']
  }" />
</template>

export default defineNuxtConfig({
  experimental: {
    normalizePageNames: false,
  },
})