GitHub 怎样为仓库设置 Issue 模板

为 GitHub 仓库设置 Issue 模板，可以从仓库的 Settings → Features → Issues → Set up templates 进入编辑器，添加模板、填写引导内容，再提交或合并到默认分支。随后打开 Issues → New issue，贡献者就能选择模板填写报告。

下面使用 GitHub.com 桌面网页和 Markdown 模板，不涉及自动化发布或 API。所有界面图均为 ImageGen 原创操作说明图，不是真实仓库截图；本文没有替读者修改仓库或创建测试 Issue。

GitHub 官方地址：https://github.com/。配置文档：https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository。

1. 准备仓库权限和模板内容

打开自己有权管理设置的仓库，点击仓库顶部 Settings。标签被收起时，从仓库导航的下拉菜单寻找；没有权限时请由仓库管理员操作，不要把个人账户设置当作仓库设置。

在 General 页面向下找到 Features，确认 Issues 已开启。若刚开启，刷新后再找模板设置按钮。可以继续的可见状态是 Issues 勾选且出现 Set up templates。

先准备四段内容：复现步骤、预期行为、实际行为、环境版本。Markdown 模板提供可编辑的正文引导，不能强制用户保留每个标题；若需要真正必填字段，应另选 YAML Issue forms，不要把模板提示误当作表单校验。

2. 从设置进入模板编辑器

点击 Set up templates，在模板管理页展开 Add template，选择 Custom template。创建后，应能看到一张可预览编辑的模板卡片和 Preview and edit 入口。

选择 Bug report 等预设也可以，但不要原样留下不适合仓库的提示。这里用自定义模板，使字段与团队真正希望收到的信息一致。

3. 填写名称、说明和正文

点击 Preview and edit，再点击铅笔编辑按钮。将模板名称填为 Defect report，说明填为“提供可复现的缺陷信息”，正文写成下面这类引导；名称应超过三个字符，并与其他模板有区别。

复现步骤：写出输入、操作顺序和最小复现条件。

预期行为：说明你认为应该发生什么。

实际行为：描述实际现象，附脱敏后的错误信息。

环境版本：填写应用版本、操作系统及必要依赖版本。

如需默认 Issue 标题，在 Optional additional information 中填入 [缺陷] 。首次设置可先不配标签和负责人，避免把不存在的标签或不合适的成员写入默认项。

切回预览，确认四段引导各自成段，没有残留示例内容或敏感信息。此时看到预览正确，只能说明编辑内容符合预期，还不代表模板已经对贡献者生效。

4. 提交模板到默认分支

点击页面右上角 Propose changes。在 Commit message 中填写“添加缺陷反馈模板”，然后按团队规则选择直接提交默认分支，或新建分支并发起 Pull request，最后点击 Commit changes。

如果走 Pull request，提交后的可见结果应是变更分支或 PR；需要等待其合并。若直接提交，检查的是默认分支已经包含本次改动。模板文件放在 .github/ISSUE_TEMPLATE 目录，Markdown 文件使用 .md；编辑器会生成相关模板元信息，不要只复制正文到仓库根目录就期待自动生效。

这一步“提交模板文件”和下一步“提交问题报告”是两件事。前者配置仓库，后者会新建一条实际 Issue。

5. 用新建 Issue 检查提交结果

模板已进入默认分支后，回到仓库顶部 Issues → New issue。在模板选择页找到 Defect report，点击对应的使用入口，常见按钮为 Get started。接下来应看到标题前缀与四段正文引导已经带入。

若只想确认模板可用，到这里即可退出，不必给真实仓库制造测试噪声。需要完整试提交流程时，在专用测试仓库填写具体内容，将标题标明为测试，再点击 Submit new issue。成功后会进入有独立编号和地址的 Issue 详情，正文应是填写后的内容，而不是模板文件本身。

没有看到模板，先看哪里？

先看仓库是否开启 Issues，再看文件是否已进入默认分支，最后看目录、扩展名及元信息是否正确。PR 尚未合并或只有普通正文文件，都不是已生效状态。

模板名称与 Issue 标题有什么不同？

名称用于选择模板；默认标题用于新建 Issue 的标题栏。两者可以不同，用户通常还能修改预填标题和正文。

怎样保证复现步骤必填？

普通 Markdown 标题不能强制填写。需要结构化必填项时使用 Issue forms，并按 GitHub 的表单语法设置字段与 required；不要把本文的 Markdown 模板直接当作 YAML 表单。

最终应分清三个结果：编辑器预览正确、模板进入默认分支、New issue 能带入内容。只有前两步都落实后，贡献者才有可重复使用的反馈入口。

更多官方说明：模板与表单区别 https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates；创建 Issue https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue。