CNB 文档

简体中文

English

简体中文

English

外观

Issue 模板

复制页面

1407 字约 5 分钟

Issue 模板 介绍如何为仓库配置 Issue 模板。

使用场景：希望 Issue 信息更完整时使用——例如让提缺陷的人自动填上复现步骤和版本号， 让提需求的人填上背景与验收标准，减少来回追问。

CNB 支持 YAML 和 Markdown 两种模板格式，把模板放在仓库的 .cnb/ISSUE_TEMPLATE 目录即可生效。

存放目录

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

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

提示

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

支持的文件格式

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

扩展名说明
.yml / .yamlYAML 表单模板，可定义各类输入组件，推荐
.mdMarkdown 模板，整篇内容原样作为 Issue 正文

文件限制

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

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

模板选择页配置（可选）

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

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

YAML 模板

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

顶层字段

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

字段类型必填说明
namestring是模板名称，展示在模板选择页
descriptionstring是模板描述，展示在模板选择页
titlestring否预填 Issue 标题，用户可修改
labelsstring[]否创建时自动添加的标签
assigneesstring[]否创建时自动指定的处理人
bodyobject[]否表单组件列表，见下文
name: Bug 反馈
description: 用于提交 Bug 的模板
title: "[Bug] "
labels: ["bug"]
assignees: ["userA"]
body:
  # ... 组件定义

表单组件

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

各组件通用属性如下：

属性类型说明
labelstring字段标题，展示在输入框上方；同时作为该字段在正文中的名称
descriptionstring字段说明，展示在标题下方，支持 Markdown
placeholderstring输入框占位提示

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

validations:
  required: true # 该字段必填

input（单行输入框）

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

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

textarea（多行输入框）

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

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

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

markdown（只读文本）

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

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

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

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

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

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

checkboxes（勾选框）

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

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

Markdown 模板

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

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

## 需求背景

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

## 期望行为

请描述你期望的交互方式……
Front Matter 字段类型必填说明
namestring是模板名称
aboutstring是模板描述
titlestring否预填 Issue 标题
labelsstring否预填标签，多个用英文逗号分隔
assigneesstring否预填处理人，多个用英文逗号分隔

创建 Issue

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

更多可参考示例仓库：issue-templates。

© 2026 cnb.cool