---
url: /zh/repo/issue-template.md
description: >
  介绍如何在仓库中配置 Issue 模板，支持 YAML 和 Markdown 两种格式， 模板需放置在 .cnb/ISSUE_TEMPLATE
  目录下，帮助规范 Issue 创建流程。
---
CNB 支持 Issue 模板，帮助团队规范 Issue 的创建流程，减少信息缺失、提升填写效率。

## 存放目录

所有 Issue 模板文件必须放在仓库**默认分支**的 `.cnb/ISSUE_TEMPLATE` 目录下，目录与文件均需提交到代码仓库中：

```text
.cnb/
└── ISSUE_TEMPLATE/
    ├── config.yml          # （可选）模板选择页配置
    ├── bug-report.yml      # YAML 格式模板
    └── feature-request.md  # Markdown 格式模板
```

> 模板默认读取仓库默认分支（如 `main` / `master`）上的内容，不在该分支上的模板不会被识别。

### 支持的文件格式

目录下支持以下格式的模板文件：

| 扩展名 | 说明 |
| ------ | ---- |
| `.yml` / `.yaml` | YAML 表单模板，可定义各类输入组件，**推荐** |
| `.md` | Markdown 模板，整篇内容原样作为 Issue 正文 |

### 文件限制

为避免超大文件影响性能，模板文件有以下限制：

* 单个模板文件大小上限 **256 KB**，超过会被忽略
* 目录下最多识别 **10** 个模板文件

## 模板选择页配置（可选）

在 `.cnb/ISSUE_TEMPLATE` 目录下放置 `config.yml`（或 `config.yaml`），可配置 Issue 创建时的模板选择页，
包括是否允许创建空白 Issue、以及展示联系链接：

```yaml
blank_issues_enabled: false # 是否允许创建空白 Issue，默认 true
contact_links:
  - name: 使用帮助
    url: https://cnb.cool/docs
    about: 使用过程中遇到的问题，可以在这里获取帮助
```

## YAML 模板

YAML 模板通过定义多个“组件”来组成表单，用户在创建 Issue 时逐项填写，填写内容会按模板顺序拼接到 Issue 正文。

### 顶层字段

YAML 模板支持以下顶层字段：

| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| `name` | string | 是 | 模板名称，展示在模板选择页 |
| `description` | string | 是 | 模板描述，展示在模板选择页 |
| `title` | string | 否 | 预填 Issue 标题，用户可修改 |
| `labels` | string\[] | 否 | 创建时自动添加的标签 |
| `assignees` | string\[] | 否 | 创建时自动指定的处理人 |
| `body` | object\[] | 否 | 表单组件列表，见下文 |

```yaml
name: Bug 反馈
description: 用于提交 Bug 的模板
title: "[Bug] "
labels: ["bug"]
assignees: ["userA"]
body:
  # ... 组件定义
```

### 表单组件

`body` 下的每一项是一个组件，通过 `type` 指定组件类型，通过 `attributes` 定义属性，通过 `validations` 定义校验规则。

各组件通用属性如下：

| 属性 | 类型 | 说明 |
| ---- | ---- | ---- |
| `label` | string | 字段标题，展示在输入框上方；同时作为该字段在正文中的名称 |
| `description` | string | 字段说明，展示在标题下方，支持 Markdown |
| `placeholder` | string | 输入框占位提示 |

校验规则通过 `validations` 声明，当前支持必填校验：

```yaml
validations:
  required: true # 该字段必填
```

#### input（单行输入框）

用于填写简短的单行文本：

```yaml
- type: input
  attributes:
    label: 版本号
    description: 你使用的产品版本
    placeholder: 例如 1.0.0
  validations:
    required: true
```

#### textarea（多行输入框）

用于填写较长文本。默认渲染为 Markdown 编辑器，支持富文本与图片上传；通过 `render: text` 可改为纯文本输入框：

```yaml
# 默认：Markdown 编辑器
- type: textarea
  attributes:
    label: 复现步骤
    placeholder: 请描述完整的复现步骤
  validations:
    required: true

# render: text 渲染为纯文本输入框
- type: textarea
  attributes:
    label: 报错日志
    render: text
    placeholder: 粘贴完整报错日志
```

#### markdown（只读文本）

用于在表单中插入只读的 Markdown 说明文字，用户无法编辑。默认该段内容**不写入** Issue 正文，仅作展示；
如需一并写入正文，设置 `includeInBody: true`：

```yaml
- type: markdown
  attributes:
    value: |
      感谢你提交 Issue，请先阅读 [贡献指南](https://cnb.cool) 再填写。
  # includeInBody 未开启时，这段文字仅展示，不写入正文

- type: markdown
  attributes:
    value: |
      ## 环境信息
    includeInBody: true # 该段文字会一并写入 Issue 正文
```

#### dropdown（下拉框）

提供选项下拉选择；默认单选，设置 `multiple: true` 支持多选：

```yaml
- type: dropdown
  attributes:
    label: 影响范围
    options:
      - 前端
      - 后端
      - 数据
  validations:
    required: true

# 多选下拉框
- type: dropdown
  attributes:
    label: 涉及模块
    multiple: true
    options:
      - 认证
      - 计费
      - 流水线
```

#### checkboxes（勾选框）

提供一组可勾选的选项，常用于自查清单；每个选项可通过 `required: true` 标记为必勾：

```yaml
- type: checkboxes
  attributes:
    label: 提交前检查
    options:
      - label: 已复现问题
        required: true
      - label: 已补充日志
      - label: 已确认无敏感信息
```

## Markdown 模板

Markdown 模板将整篇 `.md` 文件内容作为 Issue 正文展示给用户，用户可在创建页直接编辑。
文件头部的 YAML Front Matter 用于配置模板元信息：

```markdown
---
name: 功能建议
about: 用于提交功能建议
title: "[Feature] "
labels: feature
assignees: userA
---

## 需求背景

请描述你希望新增的功能……

## 期望行为

请描述你期望的交互方式……
```

| Front Matter 字段 | 类型 | 必填 | 说明 |
| ---------------- | ---- | ---- | ---- |
| `name` | string | 是 | 模板名称 |
| `about` | string | 是 | 模板描述 |
| `title` | string | 否 | 预填 Issue 标题 |
| `labels` | string | 否 | 预填标签，多个用英文逗号分隔 |
| `assignees` | string | 否 | 预填处理人，多个用英文逗号分隔 |

## 创建 Issue

在仓库“新建 Issue”页面，CNB 会自动读取 `.cnb/ISSUE_TEMPLATE` 下的模板并展示模板选择页。
选择某个模板后进入对应表单，填写完成后提交即可创建 Issue。

更多可参考示例仓库：[issue-templates](https://cnb.cool/examples/templates/issue-templates)。