GitHub Issues 怎样用表单收集结构化信息

如果团队收到的 Issue 总是缺少复现步骤、运行环境或期望结果，可以把“自由填写”改成固定字段。GitHub Issue form 使用 YAML 定义表单，提交后会把各个输入转换成 Issue 正文中的 Markdown 内容；表单文件放在仓库默认分支的 .github/ISSUE_TEMPLATE 目录中。

官方地址：https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms

下面以一个“登录失败”反馈表单为例，目标不是把 Issue 变成数据库，而是让每条反馈都至少带上可复查的四类信息：复现步骤、期望结果、实际结果和运行环境。

先把验收结果定下来

1. 打开 Issue form 的配置入口

进入目标仓库后，先确认 Issues 功能已启用。使用网页入口时，路径是“仓库首页 → Settings → Issues → Set up templates”；如果你更习惯直接改文件，也可以在默认分支中新建 .github/ISSUE_TEMPLATE/login-failure.yml。文件名使用 .yml，不要放在仓库根目录。

这一步先不要急着添加很多字段。先写出提交后必须核对的结果，后续每个控件都要能对应到一个结果字段，否则表单会变成比普通 Issue 更长的空白问卷。

2. 创建 YAML 文件并写顶层字段

在文件编辑页填写表单名称、选择器描述、默认标题和标签。name、description、body 是表单的核心顶层键；labels 和 assignees 属于提交后的默认元数据。

下面的示例只使用仓库级 Issue form 支持的常见字段。代码中的注释是给维护者看的，YAML 本身仍然保持可解析。

# 顶层信息决定模板选择页显示的名称和说明
name: 登录失败反馈
description: 收集一次可复现的登录失败问题
title: "[登录失败]: "
labels:
  - bug
  - triage
body:
  # markdown 只负责给填写者提示，不产生输入值
  - type: markdown
    attributes:
      value: |
        请先确认问题可以复现，再填写下面的字段。
  # textarea 适合承载多行步骤，required 会阻止空提交
  - type: textarea
    id: reproduce
    attributes:
      label: 复现步骤
      description: 请按实际操作顺序写出最小复现步骤。
      placeholder: 1. 打开登录页；2. 输入账号；3. 点击登录
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: 期望结果
      description: 正常情况下应该发生什么？
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: 实际结果
      description: 页面提示、状态码或异常表现是什么？
    validations:
      required: true
  # dropdown 把环境值收窄，减少同义写法
  - type: dropdown
    id: environment
    attributes:
      label: 运行环境
      options:
        - 生产环境
        - 测试环境
        - 本地开发环境
    validations:
      required: true

提交文件后，先回到仓库的 Issues 页面，再点击 New issue。如果模板选择器中能看到“登录失败反馈”，说明目录、扩展名和顶层字段已经被识别。

3. 用 body 定义真正需要收集的字段

表单字段的关键是 id、attributes 和 validations。id 是字段在配置中的稳定标识；用户看到的是 label 和 description。不要把业务字段全部做成必填，只有缺失后无法排查的问题才设置 required: true。

如果需要单选，用 dropdown 的 options；如果允许多选，可以增加 multiple: true。日志或堆栈适合使用 textarea 并设置 render，这样提交后的内容会按代码块呈现。复选框适合确认行为准则或重复检查，而不是代替长文本说明。

Issue form 只负责收集输入，不会自动替你创建数据库字段，也不会把提交内容变成独立 API 字段。团队要做统计时，仍然需要依靠稳定的标题、标签、Issue type 或后续自动化规则。

4. 提交一条样例并核对结果

按“仓库首页 → Issues → New issue → 登录失败反馈”的路径打开表单，填写四个字段后提交。提交前重点看三件事：必填项为空时是否无法继续、标题是否带上 [登录失败]: 前缀、标签是否出现 bug 和 triage。

提交后的 Issue 正文应出现“复现步骤”“期望结果”“实际结果”“运行环境”四个小节。它们仍是 Markdown 正文，不要把视觉上的小节标题误认为 GitHub 数据库中的独立字段。

验收记录可以很简单：保存一条样例 Issue 链接、表单文件路径和本次修改提交。以后表单字段发生变化时，用同一条记录对比“旧 Issue 是否仍能阅读、新 Issue 是否多出必填字段”，避免只看配置文件而忘了看真实提交结果。

表单不显示或字段为空怎么办

第一，检查文件是否已经进入默认分支；只存在于其他分支的模板不会对普通贡献者显示。第二，确认路径严格是 .github/ISSUE_TEMPLATE，文件扩展名是 .yml。第三，检查顶层是否同时存在 name、description 和 body，以及每个 body 元素是否有合法的 type。第四，确认 id 只使用稳定、唯一的短标识，required 放在对应字段的 validations 下。

如果表单能打开但提交后看不到某个字段，优先检查该字段是否真的位于 body 数组中；如果只是想给填写者看提示，应使用 markdown，不要期待它产生可填写内容。Issue form 不适用于 Pull Request，Pull Request 仍需要单独的模板。

相关问题

Issue form 能不能替代普通 Markdown 模板？

不能完全替代。Issue form 适合固定收集字段，Markdown 模板更适合长篇自由描述。两者可以同时放在同一个 .github/ISSUE_TEMPLATE 目录。

为什么必填字段仍然需要人工复核？

required: true 只能保证字段不为空，不能保证复现步骤真实、环境描述完整或结果可重现。提交后的 Issue 仍要按团队规则 triage。

字段改名会影响旧 Issue 吗？

不会回写旧正文，但会改变新 Issue 的阅读结构。改动前应保留旧字段含义，并在团队文档中记录迁移后的名称。

用 Issue form 收集结构化信息的最小闭环就是：固定文件路径、限制输入字段、提交一条样例、回到真实 Issue 核对结果。先让字段和排查动作一一对应，再考虑标签、项目和自动化扩展。