---
title: "模块"
description: "了解如何将 Nuxt 2 模块迁移到 Nuxt 3。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/migration/module-authors"
---
# 模块

> 了解如何将 Nuxt 2 模块迁移到 Nuxt 3。

## 模块兼容性

Nuxt 3 通过 `@nuxt/kit` 的自动包装器为 Nuxt 2 模块提供了基础的向后兼容层。但通常需要遵循一些步骤来使模块与 Nuxt 3 兼容，有时为实现跨版本兼容需要使用 Nuxt Bridge。

我们为使用 `@nuxt/kit` 编写适用于 Nuxt 3 的模块准备了一份[专门指南](https://nuxt.zhcndoc.com/docs/4.x/guide/modules)。目前最佳的迁移方式是遵循该指南并重写你的模块。本指南其余部分包含一些准备步骤，供你在暂不进行完整重写、但仍希望使模块兼容 Nuxt 3 时参考。

::tip{icon="i-lucide-puzzle" to="https://nuxt.zhcndoc.com/modules"}
探索与 Nuxt 3 兼容的模块。
::

### 插件兼容性

Nuxt 3 插件并不完全向后兼容 Nuxt 2。

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/plugins"}
::

### Vue 兼容性

使用 Composition API 的插件或组件需要专门支持 Vue 2 或 Vue 3。

通过使用 [vue-demi](https://github.com/vueuse/vue-demi)，它们应该可以同时兼容 Nuxt 2 和 Nuxt 3。

## 模块迁移

当 Nuxt 3 用户添加你的模块时，你将无法访问模块容器（`this.*`），因此需要使用 `@nuxt/kit` 中的工具来访问容器功能。

### 使用 `@nuxt/bridge` 测试

迁移到 `@nuxt/bridge` 是支持 Nuxt 3 的第一步也是最重要的一步。

如果你的模块中有一个 fixture 或示例，请将 `@nuxt/bridge` 包添加到其配置中（参见[示例](https://nuxt.zhcndoc.com/docs/4.x/bridge/overview#update-nuxtconfig)）

### 从 CommonJS 迁移到 ESM

Nuxt 3 原生支持 TypeScript 和 ECMAScript Modules。有关详情和升级方式，请查看[原生 ES 模块](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/esm)。

### 确保插件默认导出

如果你注入的 Nuxt 插件没有 `export default`（例如全局 Vue 插件），请确保在文件末尾添加 `export default () => { }`。

::code-group
```js [Before]
// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)
```

```js [After]
// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }
```
::

### 避免运行时模块

在 Nuxt 3 中，Nuxt 现在是仅构建时依赖，这意味着模块不应试图挂载到 Nuxt 运行时。

即使模块仅添加到 [`buildModules`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#runtimeconfig)（而不是 `modules`）中，你的模块也应该能够正常工作。例如：

- 避免在 Nuxt 模块中更新 `process.env`，然后由 Nuxt 插件读取；请改用 [`runtimeConfig`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#runtimeconfig)。
- (\*) 避免在生产环境中依赖 `vue-renderer:*` 等运行时钩子
- (\*) 避免在模块中导入 `serverMiddleware` 来添加它们。请改为通过引用文件路径来添加，以便它们独立于模块上下文

(\*) 除非仅用于 `nuxt dev` 并已用 `if (nuxt.options.dev) { }` 进行保护。

::tip
继续阅读[模块作者指南](https://nuxt.zhcndoc.com/docs/4.x/guide/modules)，了解 Nuxt 3 模块。
::

### 使用 TypeScript（可选）

虽然不是必需的，但大部分 Nuxt 生态正在转向使用 TypeScript，因此强烈建议考虑迁移。

::tip
你可以通过将 `.js` 文件重命名为 `.ts` 来开始迁移。TypeScript 设计为渐进式的！
::

::tip
你可以在 Nuxt 2 和 3 的模块与插件中使用 TypeScript 语法，而无需任何额外依赖。
::


## Sitemap

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