---
title: "兼容性"
description: "Nuxt Kit 提供了一组工具，帮助您检查模块与不同 Nuxt 版本的兼容性。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/api/kit/compatibility"
---
# 兼容性

> Nuxt Kit 提供了一组工具，帮助您检查模块与不同 Nuxt 版本的兼容性。

Nuxt Kit 工具可以在 Nuxt 3、带有 Bridge 的 Nuxt 2 甚至不带 Bridge 的 Nuxt 2 中使用。为了确保您的模块兼容所有版本，可以使用 `checkNuxtCompatibility`、`assertNuxtCompatibility` 和 `hasNuxtCompatibility` 函数。这些函数将检查当前 Nuxt 版本是否满足您提供的约束条件。您还可以使用 `isNuxt2`、`isNuxt3` 和 `getNuxtVersion` 函数进行更细粒度的检查。

## `checkNuxtCompatibility`

检查当前 Nuxt 版本是否满足约束条件。如果不满足，返回消息数组。Nuxt 2 版本还会检查对 `bridge` 的支持。

### 用法

```ts twoslash
import { checkNuxtCompatibility, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const issues = await checkNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (issues.length) {
      console.warn('发现 Nuxt 兼容性问题：\n' + issues.toString())
    } else {
      // 执行其他操作
    }
  },
})
```

### 类型

```ts
function checkNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<NuxtCompatibilityIssues>
```

### 参数

**`constraints`**：要检查的版本和构建器约束。接受以下属性：

| 属性       | 类型                                           | 是否必需    | 描述                                                                       |
| -------- | -------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `nuxt`   | `string`                                     | `false` | Nuxt 版本，采用 semver 格式。版本可按 Node.js 方式定义，例如：`>=2.15.0 <3.0.0`。             |
| `bridge` | `Record<string, string \| false>`{lang="ts"} | `false` | 指定特定 Nuxt 构建器如 `vite`、`webpack` 或 `rspack` 的版本约束，或禁用兼容性。使用 `false` 表示禁用。 |

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

## `assertNuxtCompatibility`

断言当前 Nuxt 版本满足约束条件。如果不满足，抛出包含问题列表的错误字符串。

### 类型

```ts twoslash
// @errors: 2391
import type { Nuxt, NuxtCompatibility } from '@nuxt/schema'
// ---cut---
function assertNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<true>
```

### 参数

**`constraints`**：要检查的版本和构建器约束。详情请参阅 [`checkNuxtCompatibility` 中的约束条件表](https://nuxt.zhcndoc.com/docs/3.x/api/kit/compatibility#parameters)。

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

## `hasNuxtCompatibility`

检查当前 Nuxt 版本是否满足约束条件。如果全部满足返回 `true`，否则返回 `false`。Nuxt 2 版本还会检查对 `bridge` 的支持。

### 用法

```ts twoslash
import { defineNuxtModule, hasNuxtCompatibility } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const usingNewPostcss = await hasNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (usingNewPostcss) {
      // 执行相关操作
    } else {
      // 执行其他操作
    }
  },
})
```

### 类型

```ts
function hasNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<boolean>
```

### 参数

**`constraints`**：要检查的版本和构建器约束。详情请参阅 [`checkNuxtCompatibility` 中的约束条件表](https://nuxt.zhcndoc.com/docs/3.x/api/kit/compatibility#parameters)。

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

## `isNuxtMajorVersion`

检查当前 Nuxt 实例是否为指定的主版本。

### 用法

```ts twoslash
import { defineNuxtModule, isNuxtMajorVersion } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    if (isNuxtMajorVersion(3)) {
      // 针对 Nuxt 3 执行操作
    } else {
      // 针对其他版本执行操作
    }
  },
})
```

### 类型

```ts
function isNuxtMajorVersion (major: number, nuxt?: Nuxt): boolean
```

### 参数

**`major`**：要检查的主版本号。

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

## `isNuxt3`

检查当前 Nuxt 版本是否为 3.x。

::note
建议使用 `isNuxtMajorVersion(3, nuxt)` 替代。此方法可能在 @nuxt/kit v5 或未来主版本中移除。
::

### 类型

```ts
function isNuxt3 (nuxt?: Nuxt): boolean
```

### 参数

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

## `isNuxt2`

检查当前 Nuxt 版本是否为 2.x。

::note
建议使用 `isNuxtMajorVersion(2, nuxt)` 替代。此方法可能在 @nuxt/kit v5 或未来主版本中移除。
::

### 类型

```ts
function isNuxt2 (nuxt?: Nuxt): boolean
```

### 参数

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

## `getNuxtVersion`

返回当前 Nuxt 的版本号。

### 类型

```ts
function getNuxtVersion (nuxt?: Nuxt): string
```

### 参数

**`nuxt`**：Nuxt 实例。如未提供，将通过调用 `useNuxt()` 从上下文中获取。

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/compatibility.ts)


## Sitemap

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