---
title: "创建你的第一个模块"
description: "学习如何使用官方起始模板创建你的第一个 Nuxt 模块。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.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，并实现更多功能。

使用发布脚本前，请先提交所有更改（建议你遵循[约定式提交规范](https://www.conventionalcommits.org)，以便自动提升版本号和更新变更日志），然后通过 `npm run release` 运行发布脚本。

运行发布脚本时，将执行以下操作：

- 首先运行你的测试套件，包括：
  - 运行代码格式检查（`npm run lint`）
  - 运行单元测试、集成测试和端到端测试（`npm run test`）
  - 构建模块（`npm run prepack`）
- 若测试通过，它将继续发布模块，步骤包括：
  - 根据你的约定式提交规范提升模块版本号并生成变更日志
  - 发布模块到 npm（为此，模块会再次构建，确保已更新的版本号包含在发布产物中）
  - 推送一个代表新发布版本的 Git 标签到你的远程仓库

::tip
和其他脚本一样，你可以自由调整 `package.json` 中默认的 `release` 脚本，以更好地满足你的需求。
::


## Sitemap

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