---
title: "安装自定义和社区模块"
description: 从社区注册表、Git 仓库或本地路径安装第三方模块
sidebar:
  order: 3
---

使用 BMad 安装程序从社区注册表、第三方 Git 仓库或本地文件路径添加模块。

## 何时使用

- 从 BMad 注册表安装社区贡献的模块
- 从第三方 Git 仓库安装模块（GitHub、GitLab、Bitbucket、自托管）
- 使用 BMad Builder 测试本地开发中的模块
- 从私有或自托管 Git 服务器安装模块

:::note[前置条件]
需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（npm 自带）。自定义和社区模块可以在全新安装时选择，也可以添加到现有安装中。
:::

## 社区模块

社区模块收录在 [BMad 插件市场](https://github.com/bmad-code-org/bmad-plugins-marketplace)。它们按类别组织，并锁定在经过审核的 commit 上以确保安全。

### 1. 运行安装程序

```bash
npx bmad-method install
```

### 2. 浏览社区目录

选择官方模块后，安装程序会询问：

```
Would you like to browse community modules?
```

选择 **Yes** 进入目录浏览器。你可以：

- 按类别浏览
- 查看推荐模块
- 查看所有可用模块
- 按关键词搜索

### 3. 选择模块

从任意类别中选取模块。安装程序显示描述、版本和信任等级。已安装的模块会预选以便更新。

### 4. 继续安装

选择社区模块后，安装程序将继续到自定义来源，然后是工具/IDE 配置及其余安装流程。

## 自定义来源（Git URL 和本地路径）

自定义模块可以来自任何 Git 仓库或本地目录。安装程序会解析来源、分析模块结构，并将其与其他模块一起安装。

### 交互式安装

安装过程中，在社区模块步骤之后，安装程序会询问：

```
Would you like to install from a custom source (Git URL or local path)?
```

选择 **Yes**，然后提供来源：

| 输入类型 | 示例 |
| -------- | ---- |
| HTTPS URL（任意主机） | `https://github.com/org/repo` |
| HTTP URL（任意主机） | `http://host/org/repo` |
| 带子目录的 HTTPS URL | `https://github.com/org/repo/tree/main/my-module` |
| SSH URL | `git@github.com:org/repo.git` |
| 本地路径 | `/Users/me/projects/my-module` |
| 使用 ~ 的本地路径 | `~/projects/my-module` |

安装程序会克隆仓库（URL 来源）或直接从磁盘读取（本地路径），然后展示发现的模块供你选择。

### 非交互式安装

使用 `--custom-source` 标志从命令行安装自定义模块：

```bash
npx bmad-method install \
  --directory . \
  --custom-source /path/to/my-module \
  --tools claude-code \
  --yes
```

提供 `--custom-source` 但未指定 `--modules` 时，只安装 core 和自定义模块。要同时包含官方模块，需添加 `--modules`：

```bash
npx bmad-method install \
  --directory . \
  --modules bmm \
  --custom-source https://gitlab.com/myorg/my-module \
  --tools claude-code \
  --yes
```

多个来源可用逗号分隔：

```bash
--custom-source /path/one,https://github.com/org/repo,/path/two
```

## 模块发现机制

安装程序使用两种模式在来源中查找可安装的模块：

| 模式 | 触发条件 | 行为 |
| ---- | -------- | ---- |
| 发现模式 | 来源包含 `.claude-plugin/marketplace.json` | 列出清单中的所有插件；你选择要安装哪些 |
| 直接模式 | 未找到 marketplace.json | 扫描目录中的 skill（包含 `SKILL.md` 的子目录），作为单个模块解析 |

发现模式适用于已发布的模块。直接模式适合本地开发时指向 skills 目录。

:::note[关于 `.claude-plugin/`]
`.claude-plugin/marketplace.json` 路径是多个 AI 工具安装程序采用的标准约定，用于插件可发现性。它不依赖 Claude，不使用 Claude API，也不影响你使用哪个 AI 工具。任何包含此文件的模块都可以被遵循此约定的安装程序发现。
:::

## 本地开发工作流

如果你正在使用 [BMad Builder](https://github.com/bmad-code-org/bmad-builder) 构建模块，可以直接从工作目录安装：

```bash
npx bmad-method install \
  --directory ~/my-project \
  --custom-source ~/my-module-repo/skills \
  --tools claude-code \
  --yes
```

本地来源通过路径引用，不会复制到缓存。当你更新模块源码并重新安装时，安装程序会获取最新变更。

:::caution[来源移除]
如果你在安装后删除了本地来源目录，`_bmad/` 中已安装的模块文件会保留。在恢复来源路径之前，该模块在更新时会被跳过。
:::

## 安装结果

安装后，自定义模块与官方模块一起出现在 `_bmad/` 中：

```
your-project/
├── _bmad/
│   ├── core/              # 内置核心模块
│   ├── bmm/               # 官方模块（如已选择）
│   ├── my-module/         # 你的自定义模块
│   │   ├── my-skill/
│   │   │   └── SKILL.md
│   │   └── module-help.csv
│   └── _config/
│       └── manifest.yaml  # 跟踪所有模块、版本和来源
└── ...
```

manifest 记录每个自定义模块的来源（Git 来源为 `repoUrl`，本地来源为 `localPath`），以便快速更新时能重新定位来源。

## 更新自定义模块

自定义模块参与正常的更新流程：

- **快速更新**（`--action quick-update`）：从原始来源刷新所有模块。基于 Git 的模块会重新拉取；本地模块会从来源路径重新读取。
- **完整更新**：重新运行模块选择，你可以添加或移除自定义模块。

## 创建自己的模块

使用 [BMad Builder](https://github.com/bmad-code-org/bmad-builder) 创建可供他人安装的模块：

1. 运行 `bmad-module-builder` 搭建模块结构
2. 使用各种 BMad Builder 工具添加 skill、agent 和 workflow
3. 发布到 Git 仓库或共享文件夹集合
4. 他人使用 `--custom-source <your-repo-url>` 安装

要让模块支持发现模式，请在仓库根目录包含 `.claude-plugin/marketplace.json`（这是跨工具约定，非 Claude 专属）。格式详见 [BMad Builder 文档](https://github.com/bmad-code-org/bmad-builder)。

:::tip[先在本地测试]
开发期间，使用本地路径安装模块以快速迭代，发布到 Git 仓库之前先确认一切正常。
:::