---
title: "概览"
description: "减少与 Nuxt 3 的差异，降低迁移到 Nuxt 3 的负担。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/bridge/overview"
---
# 概览

> 减少与 Nuxt 3 的差异，降低迁移到 Nuxt 3 的负担。

::note
如果你要开始一个全新的 Nuxt 3 项目，请跳过本节并前往 [Nuxt 3 安装](https://nuxt.zhcndoc.com/docs/4.x/getting-started/introduction)。
::

::warning
Nuxt Bridge 提供与 Nuxt 3 相同的功能（[文档](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/auto-imports)），但有一些限制，尤其是无法使用 [`useAsyncData`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-async-data) 和 [`useFetch`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-fetch) 组合式函数。请阅读本页其余内容以了解详情。
::

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

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

## 第一部

### 升级 Nuxt 2

确保你的开发服务器（`nuxt dev`）未在运行，删除任何包锁文件（`package-lock.json` 和 `yarn.lock`），并安装最新的 Nuxt 2 版本：

```diff [package.json]
- "nuxt": "^2.16.3"
+ "nuxt": "^2.17.3"
```

然后，重新安装你的依赖：

::code-group{sync="pm"}
```bash [npm]
npm install
```

```bash [yarn]
yarn install
```

```bash [pnpm]
pnpm install
```

```bash [bun]
bun install
```

```bash [deno]
deno install
```
::

::note
安装完成后，请确保开发和生产构建都按预期工作，然后再继续。
::

### 安装 Nuxt Bridge

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

::code-group{sync="pm"}
```bash [npm]
npm install -D @nuxt/bridge nuxi
```

```bash [yarn]
yarn add --dev @nuxt/bridge nuxi
```

```bash [pnpm]
pnpm add -D @nuxt/bridge nuxi
```

```bash [bun]
bun add -D @nuxt/bridge nuxi
```

```bash [deno]
deno add -D npm:@nuxt/bridge npm:nuxi
```
::

### 更新 `nuxt.config`

请确保在配置文件中避免使用任何 CommonJS 语法，例如 `module.exports`、`require` 或 `require.resolve`。这些语法将很快被弃用且不被支持。

你可以改用静态 `import`、动态 `import()` 和 `export default`。也可以通过将文件重命名为 [`nuxt.config.ts`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/nuxt-config) 来使用 TypeScript，我们也推荐这样做。

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

export default defineNuxtConfig({
  bridge: false,
})
```

### 更新命令

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

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

在此处尝试运行一次 `nuxt2`。你会看到应用与之前一样可用。

（如果将 'bridge' 设置为 false，你的应用将像以前一样运行而不做任何更改。）

## 升级步骤

通过 Nuxt Bridge，可以分步骤向 Nuxt 3 迁移。
下面的“升级步骤”不需要一次性完成。

- [TypeScript](https://nuxt.zhcndoc.com/docs/4.x/bridge/typescript)
- [迁移旧版组合式 API](https://nuxt.zhcndoc.com/docs/4.x/bridge/bridge-composition-api)
- [插件和中间件](https://nuxt.zhcndoc.com/docs/4.x/bridge/plugins-and-middleware)
- [迁移新的组合式 API](https://nuxt.zhcndoc.com/docs/4.x/bridge/nuxt3-compatible-api)
- [Meta 标签](https://nuxt.zhcndoc.com/docs/4.x/bridge/meta)
- [运行时配置](https://nuxt.zhcndoc.com/docs/4.x/bridge/runtime-config)
- [Nitro](https://nuxt.zhcndoc.com/docs/4.x/bridge/nitro)
- [Vite](https://nuxt.zhcndoc.com/docs/4.x/bridge/vite)

## 从 CommonJS 迁移到 ESM

Nuxt 3 原生支持 TypeScript 和 ECMAScript 模块。请查看[原生 ES 模块](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/esm)以了解更多信息和升级说明。


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.