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

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

## 模块兼容性

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

我们为使用 `@nuxt/kit` 编写 Nuxt 3 模块准备了一份[专门指南](https://nuxt.zhcndoc.com/docs/3.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/3.x/directory-structure/plugins"}
::

### Vue 兼容性

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

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

## 模块迁移

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

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

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

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

### 从 CommonJS 迁移到 ESM

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

### 确保插件默认导出

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

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

Vue.use(Vuelidate)
```

```js [之后]
// ~/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/3.x/api/nuxt-config#runtimeconfig-1)（而不是 `modules`）中，也应该能够正常工作。例如：

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

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

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

### 使用 TypeScript（可选）

虽然不是必须，但 Nuxt 生态大部分已转向使用 TypeScript，强烈建议考虑迁移。

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

::tip
你可以在无需额外依赖的情况下，为 Nuxt 2 和 Nuxt 3 的模块及插件使用 TypeScript 语法。
::


## Sitemap

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