GitHub Issue 模板怎样统一收集复现信息
如果维护者每次都要追问“怎么复现、运行什么版本、实际结果是什么”,问题通常不在提交者不配合,而在 Issue 入口没有把这些信息变成固定字段。GitHub Issue Form 可以把复现步骤、期望结果、环境、日志和截图拆成结构化输入,提交后的内容仍会进入普通 Issue,方便后续讨论。
官方地址:https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests
下面以一个需要收集 Bug 复现信息的仓库为例,只配置 Issue 模板、issue form 字段和提交入口,不涉及 Pull Request 模板。
先把入口放到仓库的模板配置里
打开目标仓库后,进入 Settings → Features → Issues。如果 Issues 尚未启用,先打开开关并刷新页面;随后点击 Set up templates,或者直接准备在仓库的 .github/ISSUE_TEMPLATE/ 目录下新建 YAML 文件。

这里有两个容易混淆的入口:
- Set up templates 适合从网页界面创建或预览模板;
- .github/ISSUE_TEMPLATE/ 是 issue form YAML 文件最终应提交到的目录。
如果仓库已经有多个 Markdown 模板,可以继续保留它们,再增加一个 YAML 表单。模板名称要有辨识度,不能只写成过短的缩写,否则可能不会显示在模板选择器中。
先按排查顺序设计字段
字段不要从“维护者想知道什么”开始堆,而要从一次排查真正需要什么开始排。建议顺序是:问题现象 → 期望结果 → 复现步骤 → 运行环境 → 日志或附件。这样提交者先描述行为,再给出可以重复执行的路径。
一份实用的字段分工如下:
| 字段 | 控件 | 建议 |
|---|---|---|
| 发生了什么 | textarea | 必填,要求写实际看到的错误或异常行为 |
| 期望结果 | textarea | 必填,避免把“没有问题”当成默认预期 |
| 复现步骤 | textarea | 必填,提示填写最小操作路径 |
| 版本或环境 | dropdown / input | 用固定选项减少同义写法 |
| 日志、截图 | textarea / upload | 可选,避免没有附件时阻塞提交 |
dropdown 适合版本、运行平台这类有限选项;自由描述应使用 textarea。不要把所有内容都做成必填,否则提交者遇到无法提供的日志时,可能随便填入无用文本。
创建一个能直接使用的 issue form
在仓库中创建 .github/ISSUE_TEMPLATE/bug-report.yml,顶层至少需要 name、description 和 body。下面的例子把复现信息放在前面,并把日志和截图留作可选材料:
# 这份文件放在 .github/ISSUE_TEMPLATE/bug-report.yml
name: Bug 复现信息
description: 按统一字段提交可复查的问题报告
title: "[Bug]: "
labels:
- needs-triage
body:
# 用说明块告诉提交者如何准备最小复现
- type: markdown
attributes:
value: |
请先搜索已有 Issue,并尽量提供最小复现步骤。
# 现象和期望结果都设为必填,避免只收到一句“不能用”
- type: textarea
id: what-happened
attributes:
label: 发生了什么
description: 请描述实际结果、错误信息或异常行为。
placeholder: 例如:点击保存后页面返回 500,但数据没有变化。
validations:
required: true
- type: textarea
id: expected-result
attributes:
label: 期望结果
description: 你原本希望系统完成什么?
validations:
required: true
- type: textarea
id: reproduce-steps
attributes:
label: 复现步骤
description: 请写出从干净环境开始的最小操作路径。
placeholder: |
1. 打开设置页
2. 输入一条记录
3. 点击保存
validations:
required: true
- type: dropdown
id: runtime
attributes:
label: 运行环境
options:
- Linux
- macOS
- Windows
validations:
required: true
- type: textarea
id: logs
attributes:
label: 相关日志
description: 可以粘贴关键日志,敏感信息请先脱敏。
render: shell
validations:
required: false
- type: upload
id: screenshots
attributes:
label: 截图或附件
description: 如有助于定位问题,可拖拽上传文件。
validations:
required: false
几个字段关系值得注意:
id是表单内部标识,建议使用稳定的英文短名,不要在同一表单里重复;validations.required只放在确实能回答的字段上;render: shell会让日志以代码块形式呈现,提交者不必自己添加反引号;- issue forms 支持输入框、下拉框、复选框和文件上传等类型,但它们只适用于 Issue,不是 Pull Request 表单。

让模板选择器减少空白提交
如果希望普通贡献者优先使用结构化模板,可以在同一目录增加 config.yml:
# 这份文件放在 .github/ISSUE_TEMPLATE/config.yml
# 关闭普通贡献者的空白 Issue,维护者仍可保留内部处理入口
blank_issues_enabled: false
contact_links:
# 将非 Bug 讨论引导到合适的社区位置
- name: 社区支持
url: https://github.com/orgs/community/discussions
about: 适合使用问题和经验交流
这里的 contact_links 只是模板选择器中的外部入口,不会替代 Issue Form。生产仓库如果有独立的安全报告入口,可以在确认地址后再增加对应链接,避免给提交者一个不存在的地址。
提交这两个文件时,建议使用能说明用途的提交信息,例如“统一 Bug Issue 的复现字段”。如果团队采用 Pull Request 流程,把文件提交到默认分支后,合并完成才会对新建 Issue 的用户生效。
从 New issue 页面确认字段真的能用
文件进入默认分支后,打开仓库的 Issues → New issue。先在模板选择器中点击“Bug 复现信息”,再按页面顺序填写一条示例报告:
- 在“发生了什么”中填写实际错误,而不是只写“有问题”;
- 在“期望结果”中写明正确行为;
- 用编号步骤描述最小复现路径;
- 选择运行环境,日志和截图只在确实有帮助时添加;
- 提交后检查 Issue 正文是否保留了字段标题和附件线索。

提交后的回答会转换成 Markdown,进入普通 Issue 正文,其他协作者仍可以像处理普通 Issue 一样评论和补充信息。维护者重点看三处:复现步骤是否能独立执行、环境字段是否明确、日志和截图是否已去除密钥或个人数据。
字段不显示或提交失败时怎么查
模板选择器看不到表单:先确认文件位于默认分支的 .github/ISSUE_TEMPLATE/,文件扩展名是 .yml 或 .yaml,并且 name 不为空。新文件尚未合并到默认分支时,New issue 页面不会使用它。
表单打开后无法保存:优先检查 YAML 缩进、重复的 id、缺失的 attributes,以及 dropdown.options 是否是列表。GitHub 文档也提供了 issue form 常见验证错误的说明,遇到红色提示时按字段位置回看,而不是先删除必填项。
收到的内容仍然不完整:不要继续增加必填字段。先把“发生了什么、期望结果、复现步骤”保留为必填,再通过 description 和 placeholder 给出一个具体示例;日志、截图、联系人等字段通常更适合可选。
一份可复用的最终确认清单
- issue form 已提交到默认分支的
.github/ISSUE_TEMPLATE/; - 表单包含现象、期望结果、复现步骤和环境字段;
- 必填项能被普通提交者回答,日志与附件没有被强制要求;
- New issue 页面能看到模板,并且提交后的正文保留字段语义;
- 示例日志、截图和联系信息不会暴露 Token、密码或个人路径。
相关问题
Issue Form 能直接替代 Pull Request 模板吗?
不能。Issue Form 用于新建 Issue;Pull Request 仍应使用单独的 Pull Request 模板。
可以同时保留 Markdown 模板和 YAML 表单吗?
可以。两种模板可以共存,选择器会按文件类型和文件名展示。
为什么日志字段不应该默认必填?
不是每个问题都有日志,强制填写会产生“无”或随意文本。把它设为可选,并在描述中提醒脱敏,通常更利于得到真实信息。
GitHub Actions 怎样上传并保留构建产物
- 上一篇
- GitHub Actions 怎样上传并保留构建产物
- 下一篇
- VS Code 怎样只关闭 CSS 文件中的颜色预览方块
-
- 文章 · 软件教程 | 9分钟前 | 故障排查 · 软件教程 · 快捷键 Intellij IDEA 导出设置 导入设置 JetBrains IDE Keymap
- JetBrains IDE 怎样导出并迁移自定义快捷键
- 322浏览 收藏
-
- 文章 · 软件教程 | 11分钟前 |
- Docker 构建怎样安排层顺序提高缓存命中
- 332浏览 收藏
-
- 文章 · 软件教程 | 14分钟前 | css · vs code · CSS VS Code 颜色预览 editor.colorDecorators
- VS Code 怎样只关闭 CSS 文件中的颜色预览方块
- 100浏览 收藏
-
- 文章 · 软件教程 | 28分钟前 |
- GitHub Actions 怎样上传并保留构建产物
- 296浏览 收藏
-
- 文章 · 软件教程 | 30分钟前 | 开发环境 · vs code · VS Code uid GID devcontainer.json Dev Containers remoteUser containerUser
- VS Code Dev Containers 怎样避免容器内文件变成 root
- 258浏览 收藏
-
- 文章 · 软件教程 | 34分钟前 | vs code · 软件教程 · 编辑器 VS Code 代码折叠 Fold Level
- VS Code 怎样用折叠级别快速收起嵌套代码
- 152浏览 收藏
-
- 文章 · 软件教程 | 36分钟前 | vs code · 软件教程 · VS Code tasks.json 任务变量 inputs
- VS Code 任务怎样用输入变量减少重复命令
- 368浏览 收藏
-
- 文章 · 软件教程 | 37分钟前 | 开发工具 · vs code · 软件教程 · VS Code settings.json Workspace settings Settings editor 设置优先级
- VS Code 设置优先级怎样定位项目配置被用户设置覆盖
- 327浏览 收藏
-
- 文章 · 软件教程 | 37分钟前 | Node.js · vs code · VS Code launch.json 多环境 调试配置
- VS Code launch.json 怎样给多环境复用调试配置
- 211浏览 收藏
-
- 文章 · 软件教程 | 1天前 |
- Docker Compose检查端口与网络解析
- 338浏览 收藏
-
- 文章 · 软件教程 | 1天前 |
- Docker Compose init怎样回收容器里的子进程
- 228浏览 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 485次学习
-
- PubMedQA
- 深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
- 1054次使用
-
- H2O EvalGPT
- H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
- 1054次使用
-
- LMArena
- LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
- 1218次使用
-
- HELM
- 深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
- 1161次使用
-
- MMBench
- MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
- 1004次使用
-
- Golang解析yaml文件操作指南
- 2022-12-26 131浏览
-
- golang解析yaml文件操作
- 2023-01-07 236浏览
-
- Golang使用第三方包viper读取yaml配置信息操作
- 2022-12-24 237浏览
-
- Go 配置文件怎样先设默认值再解码
- 2026-10-14 412浏览
-
- Go 模糊测试发现失败输入后怎么固定成回归用例
- 2026-11-10 237浏览

