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

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

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

::warning
Nuxt Bridge 提供与 Nuxt 3 相同的功能（[文档](https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/auto-imports)），但有一些限制，尤其是 [`useAsyncData`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-async-data) 和 [`useFetch`](https://nuxt.zhcndoc.com/docs/3.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`

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

你可以改用静态 `import`、动态 `import()` 和 `export default`。将文件重命名为 [`nuxt.config.ts`](https://nuxt.zhcndoc.com/docs/3.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/3.x/bridge/typescript)
- [迁移旧版 Composition API](https://nuxt.zhcndoc.com/docs/3.x/bridge/bridge-composition-api)
- [插件和中间件](https://nuxt.zhcndoc.com/docs/3.x/bridge/plugins-and-middleware)
- [迁移新版 Composition API](https://nuxt.zhcndoc.com/docs/3.x/bridge/nuxt3-compatible-api)
- [Meta Tags](https://nuxt.zhcndoc.com/docs/3.x/bridge/meta)
- [运行时配置](https://nuxt.zhcndoc.com/docs/3.x/bridge/runtime-config)
- [Nitro](https://nuxt.zhcndoc.com/docs/3.x/bridge/nitro)
- [Vite](https://nuxt.zhcndoc.com/docs/3.x/bridge/vite)

## 从 CommonJS 迁移到 ESM

Nuxt 3 原生支持 TypeScript 和 ECMAScript Modules。有关更多信息和升级说明，请查看 [Native ES Modules](https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/esm)。


## Sitemap

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