升级指南

升级 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 环境 API，以改进构建配置
• 区分大小写的路由：页面路由严格匹配 URL 的大小写，与 Nitro 保持一致
• 标准化页面名称：页面组件名称将匹配其路由名称，以确保 <KeepAlive> 行为一致
• clearNuxtState 重置为默认值：clearNuxtState 将把状态重置为其初始值，而不是将其设置为 undefined
• 非异步 callHook：callHook 可能返回 void，而不是始终返回 Promise
• 注释节点占位符：仅客户端组件使用注释节点而不是 <div>作为 SSR 占位符，修复 scoped styles hydration 问题
• 更严格的副作用导入：生成的 tsconfig.json 启用 noUncheckedSideEffectImports，以匹配 TypeScript 7 的默认设置
• Vue Options API 已禁用：为了减小客户端包体积，Options API 会从客户端包中编译移除
• 类型化页面：默认启用 experimental.typedPages，用于类型检查路由
• 忽略 TypeScript baseUrl：生成的 TypeScript 配置不再使用 compilerOptions.baseUrl解析 Nuxt 别名
• 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'
  },
}))

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

移除调用 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

{
  // 如果存在则移除 "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" }
  ]
}

- "typecheck": "nuxt prepare && vue-tsc --noEmit"
+ "typecheck": "nuxt prepare && vue-tsc -b --noEmit"

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

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