1. 先从两个崩溃瞬间说起：没有Issue模板的仓库到底有多难维护

1.1 崩溃瞬间一：一条“help”消息引发的半小时排查

如果你维护过一个稍微有点人气的 GitHub 仓库，那你大概率经历过这种场景：深夜一条新 Issue 弹了出来，标题是“help”，正文只有一句“装不上，谁来看看”。你追问系统环境、版本号、完整报错，对方隔十分钟回一个词，到最后你才发现根因和他最初的描述完全不是一回事。

我自己的一个练习项目就经常这样。读者不多，Issue 倒是收了不少，大多数反馈长这样：“报错了”“运行不了”“请问支持 Windows 吗”。没有版本号、没有操作系统、没有日志。我作为唯一的维护者，每天的工作变成了客服式追问。有一次对方只发了一张截图，截图里是终端的一小段，连输入的命令都没显示完整。我让他贴一下命令原文，他说“就是 README 里的那个”；我让他贴报错，他反问“报错不都在截图里吗”。来回四轮才确认，他用的根本不是最新代码，而是三个月前的 release，问题根源早就修掉了。

这种沟通损耗，几乎全部来自“信息没有结构化”。如果没有一个模板提前告诉用户“应该填什么”，用户就真的不知道该填什么。这不是用户不配合，而是仓库没给出配合的方向。

1.2 崩溃瞬间二：信息被拆成五条评论的Bug报告

另一次，有人提交了一份很认真的 Bug 报告——认真到让人感动。他写了很长一段文字，描述了他做的操作、看到的输出、以及他预期的结果。但关键信息依然缺了：系统环境、依赖版本、复现顺序。文字里隐含了一个前提条件“我先改了配置文件”，等到我回复时，他又补充了两条评论。最终整个 Issue 变成了一个跨评论拼图，后面参与讨论的人根本不知道哪条信息属于哪个环节。

这件事给我的触动比第一条“help”更大。因为问题不在态度，而在流程。那位贡献者已经尽力表达了，但表达得越认真，信息越散落。如果当时仓库里有一个结构化的 Bug 提交表单，他会按照字段把环境、版本、步骤、日志填得清清楚楚，我们至少能省掉三轮来回。

1.3 模板真正改变的不是格式，而是协作的“入口”

我现在对模板的价值定义非常简单：它把维护者脑子里的“问题诊断清单”前置到了用户提交之前。你在模板里问什么，用户就会回答什么；你罕见地漏问什么，用户多半也不会主动补充。所以配置模板的过程，本质上是把你过去处理 Issue 的经验结构化。

常见 Bug 报告最核心的几个信息就是：项目版本、操作系统、复现步骤、实际结果、期望结果，再加上一次“你是否搜索过已有 Issue”的自我确认。有了这些字段，一份报告里的有效信息量会从 20% 提升到 80% 以上。别把模板当成形式主义，它其实是开源协作里性价比最高的基础设施。这也是为什么我强烈建议每个仓库都配上模板，尤其是使用bug_report.yml这类 YAML 表单。

2. 用哪一种“模板”：Markdown模板和YAML表单的核心差异

2.1 传统Markdown模板：能提供框架，却拦不住乱填

先说传统方案。它本质上是一个后缀为.md的文件，放在.github/ISSUE_TEMPLATE/目录下，文件头部用 YAML front matter 写name、about、title、labels、assignees，正文就是一段预设的 Markdown 文本。

--- name: Bug report about: 提交一个 Bug 帮助项目改进 title: '[Bug]: ' labels: ['bug'] assignees: '' --- **描述 Bug** 请描述你遇到的问题。 **复现步骤** 1. 2. 3. **环境信息** - 版本： - 系统：

它的优点是很轻，写起来几乎没有成本。但缺点也很明显：GitHub 对 md 模板不做任何字段校验，用户可以把所有小节删掉，只剩一行字直接提交。你精心设计的“复现步骤”“环境信息”，对不想填的人来说就是几行注释而已。

2.2 YAML Issue Forms：必填校验、下拉选项与自动标签

从 2021 年开始，GitHub 逐步开放了 Issue Forms 能力，也就是用.yml/.yaml文件描述一张真正的表单。用户看到的不是文字模板，而是单行输入框、多行文本框、下拉菜单、复选框。有些字段可以设置必填，提交时如果为空，GitHub 会直接提示，这条 Issue 根本发不出去。

它和 Markdown 模板的核心差异可以浓缩成一张表：

需要说明的是，YAML Issue Forms 并不是要全面取代 Markdown 模板。md 模板更适合流程化文本，比如发布公告、权限申请、固定格式的通知；而 YAML 表单适合数据化收集，比如 Bug 报告、功能建议。但对大部分仓库来说，日常维护中真正需要的是 YAML 表单，也就是标题里的bug_report.yml。

2.3 动手前的三件事：路径、文件扩展名与仓库权限

配置模板之前，先确认三件事，否则后面所有步骤都是白做。

第一，模板目录必须在仓库的默认分支。所谓默认分支通常叫main或master，但也可以是别的名字，以仓库设置页展示的为准。模板推到非默认分支是无效的，后面我会单独讲这个坑。

第二，文件扩展名可以写成.yml也可以写成.yaml，GitHub 官方示例一般用.yml。我建议统一用.yml，避免团队里两个人各写一种风格。

第三，仓库必须启用 Issues 功能。在仓库的Settings -> General -> Features里，把 Issues 选项勾上。如果 Issues 没开启，模板配置得再漂亮也不会出现在任何入口。

确认完这些，我们再开始写真正的配置文件。

3. bug_report.yml 逐行拆解：写一个能自动打标签的Bug表单

3.1 头部字段：name、description、title、labels、assignees 的作用

一个 YAML 表单的头部负责两件事：定义这张卡片在“新建 Issue”页面如何展示，以及提交后自动应用哪些元数据。常用的有五个字段。

• name：模板的名字，显示在模板选择卡片上。注意用户看到的不是文件名，而是name的值。
• description：卡片上的副标题，一句话说清楚这个模板给谁用。
• title：用户进入表单后预填的标题。Bug 模板常用"[Bug]: "作为前缀，用户只需要在后面补内容。
• labels：提交后自动打上的标签，是一个数组。这里要特别提醒：标签必须已经存在于仓库中，如果标签不存在，GitHub 会静默忽略，不会自动创建。
• assignees：提交后自动指派给谁，也是一个数组。只有仓库协作者才会被成功指派，普通人名会被忽略。

name: Bug report description: 提交一个 Bug，帮助项目变得更好 title: "[Bug]: " labels: ["bug", "triage"] assignees: - "project-owner"

这里的title必须加引号，因为值以[开头，不加引号会被 YAML 解析成数组。这个细节很多人会踩，后面专门讲。

3.2 body里的五类元素：从提示信息到复选清单

body是整个表单的主体，它是一个数组，每个数组项通过type字段声明元素类型。新手最容易搞混的也是这一部分，我逐个说清。

markdown是最简单的类型，只用来显示提示信息，不收集任何数据。它的核心是attributes.value，支持用|写多行文本，适合在表单开头放“提交前请先搜索已有 Issue”这类引导。

input是单行文本输入框，适合填版本号、用户名、链接。它的attributes里有label、description、placeholder、value四个可选字段，其中label是必须的，其他按需使用。

textarea是多行文本框，适合写复现步骤、粘贴日志。它可以设置attributes.render，指定语法高亮语言，比如render: shell或render: python。这样用户粘贴日志后，在渲染视图里会变成带高亮的代码块，阅读体验好很多。

dropdown是下拉选择。这里要注意一点：它是单选，不是多选。如果需要让用户勾选多个选项，应该用checkboxes。dropdown的选项写在attributes.options下，每个选项用-开头。

checkboxes是复选清单，每个选项是一个对象，含label和required两个字段。它非常适合放“我已检查过已有 Issue”“我确认提供了完整日志”这类硬性确认项。

以上每种元素（除了markdown）都可以通过validations.required: true设置为必填。但要注意，GitHub 的这个校验只检查“是否为空”，不检查格式。比如你希望用户输入 IP 地址，这里做不到格式校验，只能保证他填了东西。

3.3 一份开箱即用的 bug_report.yml 完整示例

我把上面所有类型串起来，写一份可以直接复制使用的完整配置。你只需要把标签名、默认标题前缀改成自己仓库的即可。

name: Bug report description: 提交一个 Bug，帮助项目变得更好 title: "[Bug]: " labels: ["bug", "triage"] assignees: [] body: - type: markdown attributes: value: | 感谢你抽出时间填写这份 Bug 报告。 提交前请先搜索已有 Issue，避免重复提交。 - type: input id: version attributes: label: 项目版本 description: 你正在使用的版本号，可以从 README 或包管理器的输出里找到 placeholder: "例如 v1.4.2" validations: required: true - type: dropdown id: os attributes: label: 操作系统 description: 你运行项目的系统环境 options: - Windows 10/11 - macOS - Ubuntu / Debian - CentOS / RHEL - 其他 validations: required: true - type: textarea id: reproduce attributes: label: 复现步骤 description: 请按顺序填写，越简洁越好 placeholder: | 1. 打开终端 2. 执行 xxx 命令 3. 程序抛出错误 render: shell validations: required: true - type: textarea id: actual attributes: label: 实际结果 description: 描述你实际看到的现象 render: shell validations: required: true - type: textarea id: expected attributes: label: 期望结果 description: 描述你希望发生的现象 - type: checkboxes id: checklist attributes: label: 提交前确认 options: - label: 我已搜索过已有 Issue，确认没有重复 required: true - label: 我提供了完整的版本、系统与复现步骤 required: true - label: 如果需要，我可以提供最小复现仓库

注意几个地方：id是可选的，但如果填了，所有元素里的id必须唯一。dropdown和textarea的required是否开启，取决于你对信息质量的容忍度。我自己的习惯是：凡是要花时间排查的信息，全部设为必填，宁可在用户提交时拦一下，也不想在 issue 里来回追问。

3.4 预览与验证：别等用户提交了才发现格式错误

写完 yml 文件，别急着复制到仓库。先在本地做一次语法校验，避免 YAML 缩进问题导致表单无法渲染。最简单的办法是用 Python 的 PyYAML，一行命令搞定：

python3 -c "import yaml; yaml.safe_load(open('bug_report.yml')); print('YAML ok')"

如果你的环境里没有 PyYAML，也可以直接用 Node.js：

npx --yes js-yaml bug_report.yml

本地校验只能保证语法正确，不能保证表单渲染符合预期。所以更推荐的做法是：把.github/ISSUE_TEMPLATE/目录推到一个测试仓库，或者直接推到你自己的仓库默认分支，然后打开Issues -> New issue，选择 Bug report 模板，完整地走一遍提交流程。你可以故意留空一个必填项，看看 GitHub 是否会提示；再填一遍全部内容，看看渲染出来的结构是否清晰。

我的经验是，第一次配置时表单往往没问题，但字段顺序、提示文案、下拉选项这些细节，只有真的“以用户视角”填一遍才能发现问题。不要跳过这一步。

4. config.yml：把“新建Issue”页面做成分流闸门

4.1 blank_issues_enabled：是否允许空白Issue

仓库里除了模板文件，还应该有一个config.yml。这个文件不定义具体模板，而是控制整个“新建 Issue”页面的行为。其中最重要的字段是blank_issues_enabled。

blank_issues_enabled: false

把blank_issues_enabled设为false后，用户点击New issue时，列表中不再显示“Open a blank issue”这个空白入口。所有反馈都会被引导到模板或下方定义的链接里去。这个设置在公开仓库里尤其有用，可以过滤掉大量“一句话求助”。

但我要诚实地说一句：这个开关不是绝对的封禁。一些直接访问特定链接的方式仍然可能绕过它，所以更准确的理解是“默认不提供空白入口”，而不是“从技术上禁止空白 Issue”。它承担的工作是引导，不是强制。即便如此，我在自己的仓库里依然设置成了false，因为绝大多数用户都会老老实实从页面入口进去。

4.2 contact_links：把咨询、建议引导到讨论区

contact_links是config.yml的另一个核心配置。它可以在模板列表下方添加一组外部链接，把不适合走 Issue 的请求引走。最常见的用途是把问题咨询引导到 Discussions 讨论区，把安全漏洞引导到专门的提交通道。

blank_issues_enabled: false contact_links: - name: 项目讨论区 url: https://github.com/your-org/your-repo/discussions about: 提问、求助、交流使用方法，请到讨论区 - name: 安全漏洞上报 url: https://github.com/your-org/your-repo/security/policy about: 请勿在公开 Issue 中提交安全相关漏洞

每个链接由name、url、about三个字段组成。url必须是完整的链接地址，about是一句说明，展示在链接下方。

我见过不少仓库把“功能建议”也放进contact_links，只保留 Bug 模板。这样页面更干净，Issue 区只处理明确的缺陷，讨论区承担脑暴。如果你的项目阶段还比较早，我也建议这样做：功能讨论先发生在讨论区，真正被确认采纳后，再规规矩矩地进入开发流程。

4.3 多模板并存时的编排方法

当仓库里同时存在多个模板时，GitHub 默认按文件名的字典序排列模板卡片。如果你希望某个模板排在最前面，最简单的方法是给文件名加数字前缀，比如：

.github/ISSUE_TEMPLATE/ ├── config.yml ├── 1_bug_report.yml ├── 2_feature_request.yml └── 3_documentation.yml

这样模板列表会按照1、2、3的顺序展示，Bug 模板永远排在第一位。config.yml里的contact_links显示在模板列表下方，适合作为最后的兜底出口。

还有一个细节：当仓库里只有一个模板时，点击New issue会直接进入该模板表单，不会先出现选择页面；当模板数量变成两个或更多时，才会先展示选择卡片。所以在调试阶段，如果你只有一个模板，看到的效果和预期可能不太一样，这是正常行为。

5. 上线前绕开这五个坑：大小写、分支与YAML缩进

5.1 坑一：目录名大小写写错，模板静默失效

官方文档要求的目录路径是.github/ISSUE_TEMPLATE/，注意ISSUE_TEMPLATE是大写。GitHub 对这个路径是精确匹配的，写成.github/issue_template或.github/Issue_Template，模板可能被直接忽略，而且不会报任何错误。

这条坑之所以隐蔽，是因为很多开发者在 Windows 或 macOS 上测试时，文件系统本身对大小写不敏感，本地目录都一样，推到 GitHub 上才暴露问题。我建议你推完后，直接在 GitHub 网页端进入.github目录，确认文件夹名确实是大写的ISSUE_TEMPLATE。

5.2 坑二：config.yml 放错位置，空白Issue照常出现

config.yml必须和模板文件放在同一个目录，也就是.github/ISSUE_TEMPLATE/config.yml。放到.github/config.yml、根目录或者其他地方，都不会生效。我之前见过一个仓库，模板文件能正常显示，但blank_issues_enabled: false完全没有作用，排查了半天才发现是config.yml放到了.github根目录下。

另一个容易混淆的点是 GitLab。GitLab 的 Issue 模板路径是.gitlab/issue_templates，和 GitHub 完全不同。如果你同时维护两个平台的仓库，很容易迁移时把路径搞混，我就在自己的项目里犯过这个错。

5.3 坑三：YAML缩进错位，表单直接红屏

YAML 对缩进极其敏感。最典型的错误是把dropdown的options写到attributes外面：

# 错误写法 - type: dropdown attributes: label: 操作系统 options: - Windows

正确的写法是options必须缩进到attributes里面：

# 正确写法 - type: dropdown attributes: label: 操作系统 options: - Windows

这个错误很隐性，因为部分解析器仍然能读出内容，但表单渲染会失败或被当成非法配置。我建议在编辑器里开启 YAML 树状视图，或者直接看缩进层级，确保attributes和它的子字段始终是父子关系而不是平级关系。

5.4 坑四：模板没推到默认分支，全部白忙

模板目录必须存在于仓库的默认分支。如果你的默认分支是main，但把.github/ISSUE_TEMPLATE/推到了dev分支，那么新建 Issue 时完全看不到模板。

解决办法有两种：一是把.github相关文件合并或推送到默认分支；二是如果项目的历史原因导致默认分支不是你想用的分支，可以在仓库的Settings -> General -> Default branch里修改默认分支。改完之后，模板配置才会在新建 Issue 页面里生效。别问我为什么这个顺序这么重要，我就是那个把模板推到 dev 分支之后，在 main 上苦苦找不到模板的人。

5.5 坑五：title里的中括号，差点被 YAML 当成数组

title字段如果写成title: [Bug]: xxx，YAML 会把以[开头的值解析成数组，最终表单标题可能变成一串奇怪的表示，而不是[Bug]: xxx。解决方法是加引号：

title: "[Bug]: "

如果你用单引号也可以。这个问题同样会出现在其他以[、{、#开头的内容里。比如你想在某个description里写“以 # 开头的行会被忽略”，最好也给整个值加上引号，否则#会被当成注释。我建议凡是看起来不纯的字符串，一律用引号包裹，省得 YAML 自作聪明。

关于这些坑，我后来养成了一个习惯：每次改完模板，先在自己的仓库里新建一条 Issue 走一遍全流程，然后用它当测试样本。模板这东西，自己按下提交键之前，永远不知道用户会看到什么。折腾一次，后面能安静很久。