李丹标题

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

npmyarnpnpmbun

npx nuxt upgrade

夜间发布渠道

要在发布前使用最新的 Nuxt 构建和测试功能，请阅读 夜间发布渠道 指南。

测试 Nuxt 5

Nuxt 5 目前正在开发中。在发布之前，可以从 Nuxt 4.2+ 版本测试 Nuxt 5 的许多重大更改。

选择使用 Nuxt 5

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

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

nuxt.config.ts

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

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

Vite 环境 API：自动启用新的 Vite 环境 API，以改进构建配置
其他 Nuxt 5 改进和更改（可用时）

本节在最终发布前可能会发生变化，因此如果您正在使用 future.compatibilityVersion: 5 测试 Nuxt 5，请定期查看此处。

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

迁移到 Vite 环境 API

🚦 影响级别：中

更改内容

Nuxt 5 迁移到 Vite 6 的新环境 API，它规范了环境的概念，并为每个环境提供了更好的配置控制。

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

您可以通过设置 future.compatibilityVersion: 5（参见 测试 Nuxt 5）或通过显式启用 experimental.viteEnvironmentApi: true 来提前测试此功能。

主要更改

废弃环境特定的 extendViteConfig()：extendViteConfig() 中的 server 和 client 选项已废弃，使用时将显示警告。
插件注册已更改：使用 addVitePlugin() 注册的仅针对一个环境（通过传入 server: false 或 client: false）的 Vite 插件将不会调用其 config 或 configResolved 钩子。
共享配置：vite:extendConfig 和 vite:configResolved 钩子现在使用共享配置而不是单独的客户端/服务器配置。

更改原因

Vite 环境 API 提供

更好的开发和生产构建一致性
对环境特定配置更精细的控制
改进的性能和插件架构
支持客户端和服务器以外的自定义环境

迁移步骤

1. 迁移使用 Vite 插件

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

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

// After
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    // you can set global vite configuration here
  },
  configResolved (config) {
    // you can access the fully resolved vite configuration here
  },
  configEnvironment (name, config) {
    // you can set environment-specific vite configuration here
    if (name === 'client') {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('my-package')
    }
  },
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
}))

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

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

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

// After
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    // you can set global vite configuration here
  },
  configResolved (config) {
    // you can access the fully resolved vite configuration here
  },
  configEnvironment (name, config) {
    // you can set environment-specific vite configuration here
    if (name === 'client') {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('my-package')
    }
  },
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
}))

了解更多关于 Vite 的环境 API

迁移到 Nuxt 4

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

首先，升级到 Nuxt 4

npmyarnpnpmbun

npm install nuxt@^4.0.0

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

以下各节详细介绍了升级到 Nuxt 4 时所需的关键更改和迁移。

重大或显著更改将在下面记录，并附带迁移步骤和可用的配置选项。

使用 Codemods 迁移

为了简化升级过程，我们与Codemod团队合作，通过一些开源 codemods 自动化了许多迁移步骤。

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

有关 Nuxt 4 codemods 的完整列表、每个 codemod 的详细信息、其来源以及各种运行方式，请访问Codemod 注册表.

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

npmyarnpnpmbun

# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
npx[email protected] nuxt/4/migration-recipe

此命令将按顺序执行所有 codemods，您可以选择取消选择任何不想运行的 codemods。每个 codemod 也将在下面列出，并附带其各自的更改，并且可以独立执行。

新目录结构

🚦 影响级别：显著

Nuxt 现在默认使用新的目录结构，并向后兼容（因此，如果 Nuxt 检测到您正在使用旧结构，例如顶层 app/pages/ 目录，则此新结构将不适用）。

👉查看完整 RFC

更改内容

新的 Nuxt 默认 srcDir 默认为 app/，大多数内容都从那里解析。
serverDir 现在默认为 <rootDir>/server，而不是 <srcDir>/server
layers/、modules/ 和 public/ 默认相对于 <rootDir> 解析
如果使用Nuxt Content v2.13+，content/ RelativeTo <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

有了这个新结构，~ 别名现在默认指向 app/ 目录（您的 srcDir）。这意味着 ~/components 解析为 app/components/，~/pages 解析为 app/pages/ 等等。

👉 更多详情，请参见实现此更改的 PR.

二维码解码专题在线解析、转链接与安全避坑

李丹标题

1. 迁移使用 Vite 插件

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