GitHub Issues 如何用模板约束缺陷信息：从新建模板到提交后核对

团队用 GitHub Issues 收集缺陷时，最常见的问题不是找不到提交入口，是每个人填报的信息差异极大：有人只写一句“页面打不开”，有人贴了满屏日志却完全没提复现环境。把缺陷模板部署到仓库后，提交者点新建Issue会先看到统一的填报字段，维护者拿到内容也能快速判断复现条件、影响范围和下一步处理动作，不用来回追问补信息。

最小可用方案是：在仓库的 .github/ISSUE_TEMPLATE 中提交一个 YAML issue form，并把版本、复现步骤、期望结果和日志设为必填；改完后必须从默认分支的 New issue 页面实际提交一条测试 Issue 验收。

先把缺陷提交后的样子定下来

这个教程的目标不是把所有 GitHub 配置都讲一遍，而是做出一份能用于 Go 项目缺陷收集的最小表单。提交成功后，Issue 标题带上 [Bug] 前缀，正文至少留下版本、复现步骤、期望结果和实际结果。日志和截图属于辅助字段，可以允许为空。

name: Bug report
description: Report a reproducible problem
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: input
    id: version
    attributes:
      label: Version
      description: Tell us the commit, release, or Go version.
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Reproduction steps
      description: List the smallest reproducible steps.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected and actual result
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Logs or screenshots
    validations:
      required: false

这里的 id 是表单内部字段名，只允许使用数字、字母、-、_；name、description 和 body 是 issue form 的基本结构。把“请描述版本”写进 description 不会产生校验，真正决定能否提交的是 validations.required。

从仓库 Settings 进入模板配置

打开拥有仓库配置权限的主页，点击仓库导航中的 Settings。在左侧菜单或页面的功能区域找到 Issues，点击 Set up templates。GitHub 官方页面会展示默认模板的创建入口，这一步先确认入口可见，不用急着把所有想收集的表单字段都塞进模板里。

如果看不到 Settings 选项，通常是账号权限不足，或是页面宽度不够导致导航被收进下拉菜单。切换到仓库管理员或具备维护权限的账号后再尝试操作，不要把个人账户的全局设置页误当成仓库的专属设置页。

创建 YAML issue form 并提交到默认分支

有两条可行路径：在模板向导里创建，或者直接在仓库中新建 .github/ISSUE_TEMPLATE/bug-report.yml。对于需要稳定复用的缺陷字段，我更建议直接提交 YAML 文件，代码评审可以看见每次字段变化。

1. 在仓库页面顶部选择 Add file → Create new file。
2. 文件名填写 .github/ISSUE_TEMPLATE/bug-report.yml，粘贴上面的最小配置。
3. 向下滚动到提交区域，选择直接提交到默认分支，或是通过新分支创建 Pull Request 走合并流程。
4. 填写清楚的提交说明，例如 add bug issue form，然后提交。

如果仓库希望禁止普通贡献者绕过模板，可以在同目录增加 config.yml，写入 blank_issues_enabled: false。不过维护者仍可能看到空白 Issue 入口，所以这项配置应配合权限和团队约定理解，不能当成绝对拦截器。

在 New issue 页面检查中间状态

提交文件后，回到仓库的 Issues 标签页，点击 New issue。正常状态下，模板选择器能看到刚创建的名称和描述；点击模板后，页面应显示 Version、Reproduction steps、Expected and actual result 等预设字段，而不是一块没有结构的纯 Markdown 文本。

先故意不填必填字段，点击提交，确认页面会把焦点定位到缺失的字段附近。再补齐所有内容，输入一组可复现的测试数据，例如 Go 版本、提交号、三步复现命令和实际错误信息。这个操作能区分“系统识别到模板文件”和“字段校验逻辑真正生效”这两个不同的状态。

用一条测试 Issue 做最终验收

测试提交后，检查标题是否带有 [Bug]: 前缀，Labels 是否出现 bug 或 triage，正文是否按字段顺序留下版本、步骤和结果。若正文中出现字段标题但输入内容消失，优先检查 YAML 的缩进和字段 id 是否重复。

还要回到仓库文件页确认 YAML 文件存放在默认分支，而不是只存在于临时开发分支。GitHub 官方规则明确要求模板放在默认分支，放在其他分支时，协作者不会在新建 Issue 页面看到对应的模板选项。

模板不显示时按现象修正

• New issue 没有模板：检查目录是否精确为 .github/ISSUE_TEMPLATE，扩展名是否为 .yml，并确认文件已经进入默认分支。
• 表单打开但提交不了：检查 YAML 缩进、name、description、body 是否齐全，再检查必填字段的 validations 层级。
• 模板能提交但内容不完整：不要只增加提示语；把真正关键的字段设为 required: true，日志、截图等可选材料保持可选。
• 标签没有自动添加：确认仓库中已经存在同名标签，并检查 YAML 配置里的标签拼写；标签不存在时不要把它当成表单校验失败的问题处理。

把模板变更留下可追踪记录

最后保留模板文件的提交记录和一次真实测试 Issue 的链接。后续如果需要调整字段，优先通过 Pull Request 修改 YAML 配置，在PR描述里写清“新增了什么必填信息、会影响哪些提交者”。这样模板就不是一次性的设置项，而是随着项目排障经验不断迭代收敛的统一填报入口。

GitHub Issues 模板常见问题

Markdown 模板和 Issue form 怎么选

只需要预填一段固定文字时，Markdown 模板更轻；需要输入框、下拉框、复选框和必填校验时，选择 YAML issue form。两者都放在 .github/ISSUE_TEMPLATE，区别在于文件扩展名和字段能力。

为什么改完文件仍看不到模板

先确认改动已经合并到默认分支，再刷新 Issues 的 New issue 页面。如果模板仍不显示，检查文件名、目录层级和 YAML 语法是否符合规则，不要只看本地编辑器里文件是否存在。

当模板选择器、空值校验、最终 Issue 内容和默认分支文件都通过检查，这份缺陷模板才算真正完成部署。