升级指南

升级 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 5 从 Nuxt 版本 4.2+ 的重大更改。

选择使用 Nuxt 5

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

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

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

当您将 future.compatibilityVersion 设置为 5 时，您在 Nuxt 配置中的默认值将更改为选择 Nuxt v5 的行为，包括：

• Vite Environment API：自动启用新的 Vite Environment API，以改进构建配置
• 区分大小写的路由：页面路由将严格匹配 URL 的大小写，与 Nitro 保持一致
• 规范化的页面名称：页面组件名称将与其路由名称匹配，以确保 <KeepAlive> 行为一致
• clearNuxtState 重置为默认值：clearNuxtState 将把状态重置为其初始值，而不是将其设置为 undefined
• 非异步 callHook：callHook 可能返回 void，而不是始终返回 Promise
• 注释节点占位符：仅客户端组件使用注释节点而不是 <div>作为 SSR 占位符，修复作用域样式的 hydration 问题
• 更严格的副作用导入：生成的 tsconfig.json 启用 noUncheckedSideEffectImports，以匹配 TypeScript 7 的默认设置
• 禁用 Vue Options API：Options API 会从客户端 bundle 中编译移除，以减小其体积
• 类型化页面：默认启用 experimental.typedPages，以支持类型检查的路由
• Nuxt 5 发布后提供的其他改进和变更

重大或显著的变化将在下面注明，并附上向后/向前兼容的迁移步骤。

区分大小写的路由

🚦 影响级别：最低

变更内容

使用 compatibilityVersion: 5 时，页面路由将以区分大小写的方式匹配 URL，与 Nitro 保持一致。例如，/About 不再匹配 pages/about.vue。

迁移步骤

更新链接，使其使用与页面路由相同的大小写。若要保持不区分大小写的匹配：

export default defineNuxtConfig({
  router: {
    options: {
      sensitive: false,
    },
  },
})

jiti 不再打包

🚦 影响级别：中等

变更内容

Nuxt 不再依赖 jiti。在 bundler 外部加载的文件（nuxt.config.ts、modules/ 中的文件以及 layer 配置）现在由运行时本身导入。

你仍然可以使用 TypeScript 编写配置。 Nuxt 5 要求 Node 22.19 或更高版本，此时类型剥离默认开启，因此 nuxt.config.ts 和 TypeScript 模块会原生加载。运行时有两件过去由 jiti 代为处理、但现在不会处理的事情：猜测文件扩展名，以及编译会生成代码的 TypeScript 语法。

否则，这两类问题只有在 Nuxt 加载文件时才会暴露出来，因此生成的 node tsconfig 现在会按照运行时所见的方式描述环境（将 module 和 moduleResolution 设置为 nodenext，并加入 erasableSyntaxOnly），TypeScript 也会提前报告这两类问题。

这只涵盖 nuxt.config、modules/ 和 layer 配置。你的应用代码和 shared/ 代码会经过 Vite，并按照一直以来的方式解析。如果你需要之前的行为，可以覆盖配置：

export default defineNuxtConfig({
  typescript: {
    nodeTsConfig: {
      compilerOptions: {
        module: 'preserve',
        moduleResolution: 'bundler',
        erasableSyntaxOnly: false,
      },
    },
  },
})

变更原因

每次安装 Nuxt 时，都会引入 jiti 来加载少量文件，而其中大多数文件现在运行时已经可以在没有辅助的情况下加载。移除它可以减小默认安装的体积。

迁移步骤

1. 为相对导入添加文件扩展名。

nuxt.config.ts、modules/ 和 layer 配置中的相对导入需要显式指定扩展名：

- import { myPlugin } from './build/my-plugin'
+ import { myPlugin } from './build/my-plugin.ts'

TypeScript 会以 TS2835 报告缺少扩展名。请注意，它的快速修复建议使用 ./build/my-plugin.js；应填写文件实际使用的扩展名（.ts），Node 会直接解析该扩展名。

裸包导入（import { defu } from 'defu'）不受影响。

2. 使用可擦除的 TypeScript 语法。

类型注解会被擦除，但会生成运行时代码的语法则无法使用。在配置文件和模块文件中，将以下内容替换为：

• 用 const 对象替换 enum Foo {}
• 用普通导出替换 namespace／module 代码块
• 将构造函数参数属性（constructor(private x: string) {}）替换为显式赋值
• 实验性装饰器

TypeScript 会以 TS1294 为你报告这些问题。

3. 如果你发布 layer 或模块，请提供编译后的 JavaScript。

这一点仅适用于包。无论配置如何，运行时都拒绝从 node_modules 内的任何文件中剥离类型，因此使用 TypeScript 编写的已发布入口无法原生加载，不论 Node 版本有多新。发布前请先编译为 JavaScript；如果你的包包含 nuxt.config，请将其输出为 nuxt.config.mjs。否则，每个使用该包的项目都必须安装 jiti。

这不适用于你自己项目中的 layer：layers/*/nuxt.config.ts 会原生加载。

4. 如果仍然需要 jiti，请安装它。

jiti 现在是可选的 peer dependency。安装后，只要运行时无法自行加载文件，Nuxt 就会自动将其作为回退方案使用：

npm i -D jiti

yarn add -D jiti

pnpm add -D jiti

bun add -D jiti

无论使用哪个 Node 版本，nuxt.schema 文件始终需要 jiti：其中的 JSDoc 注解是通过导入时转换读取的，而不是通过导入文件读取的。

随之而来的还有一项较小的变更：postcss.plugins 中指定的 PostCSS 插件现在由运行时解析，因此仅能通过 Nuxt alias 条目解析的插件名称将不再加载。请使用包名称或路径。

迁移到 Vite 环境 API

🚦 影响级别：中等

变化内容

Nuxt 5 迁移到 Vite 6 的新 环境 API。该 API 正式化了环境的概念，并提供了对每个环境配置的更好控制。

之前，Nuxt 使用单独的客户端和服务器 Vite 配置。现在，Nuxt 使用共享的 Vite 配置，并配备特定于环境的插件。这些插件使用 applyToEnvironment() 方法来针对特定环境。

关键变化：

1. 不再支持特定于环境的 extendViteConfig()：extendViteConfig() 中的 server 和 client 选项已被弃用，使用时将显示警告。
2. 更改插件注册：使用 addVitePlugin() 注册的 Vite 插件，如果仅针对一个环境（通过传递 server: false 或 client: false）将不会调用其 config 或 configResolved 钩子。
3. 共享配置：vite:extendConfig 和 vite:configResolved 钩子现在与共享配置一起工作，而不是单独的客户端／服务器配置。

变更原因

Vite 环境 API 提供了：

• 更好的一致性：确保开发与生产构建之间差异最小化
• 更细粒度的环境特定配置控制
• 改进的性能与插件架构
• 支持自定义环境，而不仅仅是客户端和服务器

迁移步骤

1. 迁移到使用 Vite 插件

我们建议您使用 Vite 插件，而不是 extendViteConfig、vite:configResolved 和 vite:extendConfig。

// 之前
extendViteConfig((config) => {
  config.optimizeDeps.include.push('my-package')
}, { server: false })

nuxt.hook('vite:extendConfig' /* or vite:configResolved */, (config, { isClient }) => {
  if (isClient) {
    config.optimizeDeps.include.push('my-package')
  }
})

// 之后
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    // 这里可以设置全局 vite 配置
  },
  configResolved (config) {
    // 这里可以访问完整解析后的 vite 配置
  },
  configEnvironment (name, config) {
    // 这里可以设置特定环境的 vite 配置
    if (name === 'client') {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('my-package')
    }
  },
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
}))

2. 迁移 Vite 插件以使用环境

您可以使用插件中的新 applyToEnvironment 钩子，而不是使用 addVitePlugin 结合 server: false 或 client: false。

// 之前
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    config.optimizeDeps.include.push('my-package')
  },
}), { client: false })

// 之后
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    // 这里可以设置全局 vite 配置
  },
  configResolved (config) {
    // 这里可以访问完整解析后的 vite 配置
  },
  configEnvironment (name, config) {
    // 这里可以设置特定环境的 vite 配置
    if (name === 'client') {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('my-package')
    }
  },
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
}))

export default defineNuxtConfig({
  extends: ['github:my-org/my-theme'],
})

{
  "devDependencies": {
    "my-theme": "github:my-org/my-theme#4a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b"
  }
}

export default defineNuxtConfig({
  extends: ['my-theme'],
})

npm install -D giget

yarn add -D giget

pnpm add -D giget

bun add -D giget

如果在未安装 giget 的情况下解析远程层，Nuxt 会报告哪个 extends 条目需要它。

非异步 callHook

🚦 影响级别：最小

变化内容

随着升级到 hookable v6，callHook 现在可能返回 void，而不是始终返回 Promise<void>。这是一项重要的性能改进：当没有注册的钩子，或所有钩子都是同步时，避免了不必要的 Promise 分配。

默认情况下（当 compatibilityVersion: 4），Nuxt 会用 Promise.resolve() 包装 callHook，以确保现有的 .then() 和 .catch() 链式调用继续正常工作。当 compatibilityVersion: 5 时，这个包装将被移除。

变更原因

Hookable v6 的 callHook 快了 20–40 倍，因为它在不需要时不会创建 Promise。这对拥有很多钩子调用点的应用有利。

迁移步骤

如果你或你的模块在使用 callHook 时配合 .then() 或 .catch() 链式调用，请改为使用 await：

- nuxtApp.callHook('my:hook', data).then(() => { ... })
+ await nuxtApp.callHook('my:hook', data)

- nuxtApp.hooks.callHook('my:hook', data).catch(err => { ... })
+ try { await nuxtApp.hooks.callHook('my:hook', data) } catch (err) { ... }

或者，你可以通过以下方式确保 callHook 始终返回一个 Promise：

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

仅客户端注释占位符

🚦 影响级别：最小

变化内容

当 compatibilityVersion: 5 时，仅客户端组件（.client.vue 文件和 createClientOnly() 的封装）现在会在服务器端渲染一个 HTML 注释（<!--placeholder-->），而不是渲染一个空的 <div> 元素。

变更原因

当占位符 <div> 和实际组件根节点使用相同的标签名时，Vue 的运行时在 hydration 过程中会跳过重新应用 setScopeId。这会导致组件挂载后 scoped styles 缺失。使用注释节点可以完全避免标签名冲突。

迁移步骤

如果你依赖占位符 <div> 继承属性（class、style 等）以用于布局目的（例如：预留空间以防止布局抖动），请改为使用 <ClientOnly> 并配合 #fallback 插槽来包裹该组件：

- <MyComponent class="placeholder" style="min-height: 200px" />
+ <ClientOnly>
+   <MyComponent />
+   <template #fallback>
+     <div class="placeholder" style="min-height: 200px"></div>
+   </template>
+ </ClientOnly>

或者，你可以通过以下方式恢复到之前的 <div> 占位符行为：

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

更严格的副作用导入

🚦 影响级别：最小

变化内容

当使用 compatibilityVersion: 5 时，Nuxt 生成的 tsconfig.json 会启用 noUncheckedSideEffectImports。这是 TypeScript 7 中的默认设置，因此尽早采用它可以让您的项目在升级前保持一致。

启用此选项后，TypeScript 无法解析到模块的仅副作用导入（import './setup'）现在会成为类型错误，而之前会被忽略。这只影响类型检查（nuxt typecheck 和您的编辑器），不影响运行时行为。

变更原因

无法解析的副作用导入会被静默忽略，因此拼写错误或已删除文件可能仍能通过类型检查。将其标记出来可以捕获这些错误，并与 TypeScript 7 默认行为保持一致。

迁移步骤

如果类型检查现在对非代码资源的副作用导入报错（例如 import '~/assets/styles.css'），请添加一个环境模块声明，以便 TypeScript 知道该导入是有效的：

declare module '*.css' {}

export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        noUncheckedSideEffectImports: false,
      },
    },
  },
})

默认禁用 Vue Options API

🚦 影响级别：最小

变化内容

当 compatibilityVersion: 5 时，Nuxt 会将 Vue 的 __VUE_OPTIONS_API__ 特性标志设置为 false，从而将 Vue 的 Options API 运行时代码从客户端包中编译移除。

变更原因

尽管大多数 Nuxt 应用都使用 Composition API 和 <script setup> 编写，但 Options API 运行时代码仍会出现在每个客户端包中。移除它可以缩小客户端包体积（在一个最小化应用中约减少 6 kB，压缩后约 2 kB）。

迁移步骤

如果您的任何组件（或依赖中的组件）使用了 Options API（export default { data() {}, methods: {}, ... }），请在您的 nuxt.config 中重新启用它：

export default defineNuxtConfig({
  vue: {
    optionsApi: true,
  },
})

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

- nuxtApp.callHook('my:hook', data).then(() => { ... })
+ await nuxtApp.callHook('my:hook', data)

- nuxtApp.hooks.callHook('my:hook', data).catch(err => { ... })
+ try { await nuxtApp.hooks.callHook('my:hook', data) } catch (err) { ... }

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

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

# 由于 https://github.com/codemod/codemod/issues/1710，使用固定版本
npx codemod@0.18.7 nuxt/4/migration-recipe

# 由于 https://github.com/codemod/codemod/issues/1710，使用固定版本
yarn dlx codemod@0.18.7 nuxt/4/migration-recipe

# 由于 https://github.com/codemod/codemod/issues/1710，使用固定版本
pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe

# 由于 https://github.com/codemod/codemod/issues/1710，使用固定版本
bun x codemod@0.18.7 nuxt/4/migration-recipe

# 使用固定版本，原因同上
deno x codemod@0.18.7 nuxt/4/migration-recipe

.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

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

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

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

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

// 加载顺序（已修正）：
// 1. layer-module-1
// 2. layer-module-2
// 3. project-module-1 （可覆盖层模块）
// 4. project-module-2 （可覆盖层模块）

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

├─ components/
├─── SomeFolder/
├───── MyComponent.vue

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

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

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

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

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

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

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

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

export default defineNuxtConfig({
  features: {
    inlineStyles: true,
  },
})

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

// 在动态页面（例如 `[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,
  },
})

// @errors: 2322
const { refresh } = await useAsyncData(() => Promise.resolve({ message: 'Hello, Nuxt!' }))

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

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

builder:watch 中使用绝对路径监听

🚦 影响级别：最小

变化内容

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

变更原因

此变更支持监听 srcDir 之外的路径，并且更好地支持图层等复杂模式。

迁移步骤

我们已经主动迁移了已知使用该钩子的官方 Nuxt 模块，详见 issue #25339。

如果你是模块作者，并想同时兼容 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))
    // ...
  })

移除 window.__NUXT__ 对象

变化内容

在应用完成 hydration 后，我们移除了全局的 window.__NUXT__ 对象。

变更原因

这为多应用模式（#21635）铺平道路，并让我们专注于访问 Nuxt 应用数据的唯一途径 —— useNuxtApp()。

迁移步骤

这些数据仍然可用，但需要通过 useNuxtApp().payload 访问：

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

目录索引扫描

🚦 影响级别：中等

变化内容

app/middleware/ 文件夹内的子文件夹也会被扫描它们的 index 文件，这些文件也会被注册为项目中间件。

变更原因

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

app/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。

迁移步骤

我们已经针对使用 EJS 语法的模块提交了 PR，但如果你需要自行处理，有三种兼容方案：

• 将字符串插值逻辑直接写入 getContents()。
• 使用自定义函数处理替换，如 https://github.com/nuxt-modules/color-mode/pull/240。
• 将 es-toolkit/compat（lodash template 的替代品）作为你项目的依赖，而非 Nuxt：

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

最后，如果你使用了模板工具函数（如 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

{
  // 如果存在则移除 "extends": "./.nuxt/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. 将所有类型增强代码归入相应上下文：
   • 应用端的增强放入 app/ 目录。
   • 服务端的增强放入 server/ 目录。
   • 应用与服务端共享的增强放入 shared/ 目录。
   增强代码如果放在 app/、server/ 或 shared/ 目录之外，将无法兼容新的项目引用机制。
5. 如需定制 TypeScript 配置，在配置中添加：

   export default defineNuxtConfig({
     typescript: {
       // 自定义 tsconfig.app.json
       tsConfig: {
         // ...
       },
       // 自定义 tsconfig.shared.json
       sharedTsConfig: {
         // ...
       },
       // 自定义 tsconfig.node.json
       nodeTsConfig: {
         // ...
       },
     },
     nitro: {
       typescript: {
         // 自定义 tsconfig.server.json
         tsConfig: {
           // ...
         },
       },
     },
   })
   

6. 更新 CI/构建脚本，确保使用新的项目引用方式。

新配置为可选项：提供更好的类型安全与智能提示，同时对现有项目保持完整兼容。

移除实验性功能配置

🚦 影响级别：最小

变化内容

Nuxt 4 不再允许配置以下四个实验性功能：

• experimental.treeshakeClientOnly：将默认开启（自 v3.0 起即默认）
• experimental.configSchema：将默认开启（自 v3.3 起即默认）
• experimental.polyfillVueUseHead：将默认关闭（自 v3.4 起即默认）
• experimental.respectNoSSRHeader：将默认关闭（自 v3.4 起即默认）
• experimental.viteEnvironmentApi：现在始终启用，且不可禁用

变更原因

这些选项长期默认开启或关闭，目前没有理由保留为可配置状态。

迁移步骤

• polyfillVueUseHead 可通过用户插件实现，示例
• respectNoSSRHeader 可通过服务器中间件实现，示例。

移除顶层 generate 配置项

🚦 影响级别：最小

变化内容

Nuxt 4 不再支持顶层的 generate 配置，包括其所有属性：

• generate.exclude —— 排除预渲染路由
• generate.routes —— 指定预渲染路由

变更原因

顶层 generate 配置是 Nuxt 2 的遗留，现在优先使用 nitro.prerender 配置。

迁移步骤

使用对应的 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']
+   }
+ }
})

标准化页面组件名称

🚦 影响级别：最小

变化内容

当设置 future.compatibilityVersion 为 5（或启用 experimental.normalizePageNames）时，页面组件名称将匹配其路由名称，而不是使用文件名。例如，pages/foo/index.vue 组件名将变为 foo，而不是 index。

变更原因

之前，Vue 会根据文件名赋予组件名，导致多个页面（如 pages/foo/index.vue 和 pages/bar/index.vue）都拥有组件名 index。这会导致 <KeepAlive> 结合 include/exclude 过滤器时效果不可靠，并且需要在每个页面手动添加 defineOptions({ name: '...' })。

迁移步骤

如果你依赖当前的组件名（例如在 <KeepAlive> 的 include 或 exclude 列表中），请更新为使用路由名称，而非文件名。

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

若要禁用此行为：

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

Nuxt 2 与 Nuxt 3+

下表简要比较了 Nuxt 的三个版本：

Nuxt 2 升级到 Nuxt 3+

迁移指南提供了 Nuxt 2 与 Nuxt 3+ 特性对比，并指导如何适配你的应用。

Nuxt 2 升级到 Nuxt Bridge

若想逐步迁移 Nuxt 2 应用到 Nuxt 3，可使用 Nuxt Bridge。它是一个兼容层，允许你在 Nuxt 2 中使用部分 Nuxt 3+ 特性，需主动开启。