---
title: "创建你的第一个模块"
description: "学习如何使用官方起始模板创建你的第一个 Nuxt 模块。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/guide/modules/getting-started"
---
# 创建你的第一个模块

> 学习如何使用官方起始模板创建你的第一个 Nuxt 模块。

## 创建模块

我们推荐你使用我们的[起始模板](https://github.com/nuxt/starter/tree/module)来开始学习 Nuxt 模块：

::code-group{sync="pm"}
```bash [npm]
npm create nuxt -- -t module my-module
```

```bash [yarn]
yarn create nuxt -t module my-module
```

```bash [pnpm]
pnpm create nuxt -t module my-module
```

```bash [bun]
bun create nuxt --template=module my-module
```
::

这将创建一个名为 `my-module` 的项目，包含开发和发布模块所需的所有样板代码。

**下一步：**

1. 在你喜欢的 IDE 中打开 `my-module`
2. 使用你喜欢的包管理器安装依赖
3. 使用 `npm run dev:prepare` 准备本地文件以供开发
4. 按照本文档深入了解 Nuxt 模块

## 使用起始模板

了解如何使用模块起始模板执行基础操作。

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/navigating-the-official-starter-template?friend=nuxt" target="_blank"}
观看 Vue School 关于 Nuxt 模块起始模板的视频。
::

### 开发你的模块

你的模块源代码位于 `src` 目录中，但开发模块时通常需要有一个 Nuxt 应用来进行测试。这就是 `playground` 目录的作用。它是一个 Nuxt 应用，你可以在其中进行调试，并且已配置好可与模块一起运行。

你可以像使用任何 Nuxt 应用一样操作 playground。

- 使用 `npm run dev` 启动其开发服务器，当你修改 `src` 目录中的模块时，它会自动重新加载
- 使用 `npm run dev:build` 构建它

::note
所有其它 `nuxt` 命令都可以针对 `playground` 目录使用（例如：`nuxt <COMMAND> playground`）。你也可以在 `package.json` 中声明额外的 `dev:*` 脚本并引用它们以便使用。
::

### 运行测试

模块起始模板包含一个基础测试套件：

- 基于 [ESLint](https://eslint.org) 的代码规范检查，使用 `npm run lint` 运行
- 基于 [Vitest](https://vitest.dev) 的测试运行器，使用 `npm run test` 或 `npm run test:watch` 运行

::tip
你可以根据需要增强默认的测试策略。
::

### 构建你的模块

Nuxt 模块自带由 [`@nuxt/module-builder`](https://github.com/nuxt/module-builder#readme) 提供的构建器。该构建器无需你进行任何配置，支持 TypeScript，并确保你的资源正确打包，方便分发给其它 Nuxt 应用。

你可以通过运行 `npm run prepack` 构建模块。

::tip
虽然在某些情况下构建模块很有用，但大多数时候你不需要自己构建：`playground` 在开发时会自动处理，发布脚本在发布时也会帮你完成。
::

### 发布到 npm

::important
在发布模块到 npm 之前，确保你拥有一个 [npmjs.com](https://www.npmjs.com) 账户，并且已经通过 `npm login` 在本地进行了认证。
::

虽然你可以通过升级版本并使用 `npm publish` 命令来发布模块，模块起始模板还提供了一个发布脚本，帮助你确保发布到 npm 的模块版本是可用的，并且包含更多功能。

使用发布脚本前，请先提交所有更改（建议遵循 [Conventional Commits](https://www.conventionalcommits.org) 规范，这样可以自动完成版本升级和变更日志更新），然后运行 `npm run release`。

发布脚本运行时会进行以下操作：

- 首先，运行你的测试套件：
  - 执行代码规范检查 (`npm run lint`)
  - 执行单元测试、集成测试和端到端测试 (`npm run test`)
  - 构建模块 (`npm run prepack`)
- 如果测试通过，将继续发布模块：
  - 根据 Conventional Commits 规范升级模块版本并生成变更日志
  - 发布模块到 npm（到此步骤模块将被重新构建，以确保已更新的版本号被包含在发布产物中）
  - 将代表新发布版本的 git 标签推送到远程仓库

::tip
和其它脚本一样，你可以根据需要调整 `package.json` 中的默认 `release` 脚本。
::


## Sitemap

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