v3.17
Nuxt on GitHub

Compatibility

以下是 nuxt.com 文档“Compatibility”部分的中文翻译，严格保留了原本的语法格式：

以下是 nuxt.com 文档“Compatibility”部分的中文翻译，严格保留了原本的语法格式：

---
title: "兼容性"
description: Nuxt Kit 提供了一组实用工具，帮助您检查模块与不同 Nuxt 版本的兼容性。
links:
  - label: 源代码
    icon: i-simple-icons-github
    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/compatibility.ts
    size: xs
---

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 { defineNuxtModule, checkNuxtCompatibility } 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 {
      // 执行某些操作
    }
  }
})

类型

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

参数

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

属性类型必需描述
nuxtstringfalseNuxt 版本，采用 semver 格式。版本可以按照 Node.js 的方式定义，例如：>=2.15.0 <3.0.0。
bridgeRecord<string, string | false>false指定特定 Nuxt 构建器（如 vite、webpack 或 rspack）的版本约束或禁用兼容性。使用 false 禁用。

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

assertNuxtCompatibility

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

类型

function assertNuxtCompatibility(constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<true>;

参数

constraints: 要检查的版本和构建器约束。详细信息请参阅 checkNuxtCompatibility 的约束表格。

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

hasNuxtCompatibility

检查当前 Nuxt 版本是否满足约束条件。如果所有约束都满足，返回 true，否则返回 false。Nuxt 2 版本还会检查 bridge 支持。

使用

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 {
      // 执行其他操作
    }
  }
})

类型

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

参数

constraints: 要检查的版本和构建器约束。详细信息请参阅 checkNuxtCompatibility 的约束表格。

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

isNuxtMajorVersion

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

使用

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

export default defineNuxtModule({
  async setup () {
    if (isNuxtMajorVersion(3)) {
      // 为 Nuxt 3 执行某些操作
    } else {
      // 为其他版本执行其他操作
    }
  }
})

类型

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

参数

major: 要检查的主版本。

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

isNuxt3

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

请使用 isNuxtMajorVersion(2, nuxt) 替代。此功能可能在 @nuxt/kit v5 或未来的主版本中移除。

类型

function isNuxt3(nuxt?: Nuxt): boolean;

参数

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

isNuxt2

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

请使用 isNuxtMajorVersion(2, nuxt) 替代。此功能可能在 @nuxt/kit v5 或未来的主版本中移除。

类型

function isNuxt2(nuxt?: Nuxt): boolean;

参数

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

getNuxtVersion

返回当前 Nuxt 版本。

类型

function getNuxtVersion(nuxt?: Nuxt): string;

参数

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