Nuxt 3 已于 31 July 2026 结束生命周期
此版本将不再接收错误修复或安全补丁。 升级到 Nuxt 4 或获取 HeroDevs 提供的延长支持

概览

缩小与 Nuxt 3 的差异，减少迁移到 Nuxt 3 的负担。

Maschinelle Übersetzung ·2 % geprüft

如果你要开始一个全新的 Nuxt 3 项目，请跳过本节并前往 Nuxt 3 Installation。
Nuxt Bridge 提供与 Nuxt 3 相同的功能（文档），但有一些限制，尤其是 useAsyncData 和 useFetch 组合式函数不可用。详情请阅读本页其余内容。

Bridge 是一个前向兼容层，允许你通过简单安装并启用一个 Nuxt 模块，体验许多 Nuxt 3 的新功能。

使用 Nuxt Bridge，你可以确保你的项目（几乎）已为 Nuxt 3 准备好，并可以逐步推进向 Nuxt 3 的迁移。

第一步

升级 Nuxt 2

确保你的开发服务器（nuxt dev）未运行，移除任何锁定文件（package-lock.json 和 yarn.lock），然后安装最新版的 Nuxt 2：

package.json
- "nuxt": "^2.16.3"
+ "nuxt": "^2.17.3"

然后，重新安装依赖：

npm install
安装完成后，请确认开发和生产构建均按预期工作，然后再继续下一步。

安装 Nuxt Bridge

将 @nuxt/bridge 和 nuxi 作为开发依赖安装：

npm install -D @nuxt/bridge nuxi

更新 nuxt.config

请确保你的配置文件中避免使用诸如 module.exports、require 或 require.resolve 的 CommonJS 语法。这些语法很快将被废弃且不再支持。

你可以改用静态 import、动态 import() 和 export default。将文件重命名为 nuxt.config.ts 以使用 TypeScript 也是可行且推荐的做法。

nuxt.config.ts
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: false,
})

更新命令

nuxt 命令现在应改为 nuxt2 命令。

{
  "scripts": {
-   "dev": "nuxt",
+   "dev": "nuxt2",
-   "build": "nuxt build",
+   "build": "nuxt2 build",
-   "start": "nuxt start",
+   "start": "nuxt2 start"
  }
}

此处尝试运行一次 nuxt2。你会看到应用程序与之前一样正常运行。

（如果 bridge 设置为 false，应用将像以前一样无变化地运行。）

升级步骤

借助 Nuxt Bridge，迁移到 Nuxt 3 可以分步进行。以下“升级步骤”无需一次完成。

从 CommonJS 迁移到 ESM

Nuxt 3 原生支持 TypeScript 和 ECMAScript Modules。有关更多信息和升级说明，请查看 Native ES Modules。