GitHub Issues 与 Projects初学者指南

#

为什么要使用 Issues 与 Projects

#

GitHub Issues 与 Projects 是团队协作与任务管理的核心工具。

• Issues：用于记录任务、bug、想法或需求，是项目中最小的工作单元，便于团队讨论与追踪。
• Projects：提供一个可视化看板（board），把多个 Issue 聚合并呈现为状态栏（例如 To do / In progress / Done），更容易规划与优先级管理。

将两者结合后，你可以在 Issue 层面沟通和记录细节，在 Project 层面查看全局进度与优先级，实现透明、可追踪的团队协作流程。

创建你的第一个 GitHub Issue

#

Issue 非常适合快速捕捉需要关注的事项（新功能、Bug、任务等）。下面是在示例仓库中创建 Issue 的基本步骤：

示例仓库（可用于练习）：https://github.com/github-samples/gitfolio?utm_source=blog-episode-1&utm_medium=blog&utm_campaign=gfb-s3-2026

1. 在浏览器打开示例仓库页面（或你自己的仓库）。
2. 点击页面上方的 Issues 标签。
3. 右上角点击绿色 New issue 按钮。
4. 在 “Add a title” 框中输入清晰的标题。
5. 在 “Add a description” 框中写明问题或任务的详细描述：预期行为、复现步骤、影响范围等，让修复/实现者能明确预期。
6. 右侧可以配置：
   • Assignee（指派人）
   • Labels（标签）
   • Type（类型，例如 bug、task）
   • Projects（将 Issue 加入 Project）
   • Milestone（里程碑）
7. 点击页面底部的绿色 Create 按钮。

创建后，团队成员可以在 Issue 下发表评论、上传图片、添加引用等。你也可以通过在评论或 PR 描述中输入 # 加上 Issue 编号来引用其他 Issue（GitHub 会自动生成可点链接）。

当工作完成时，关闭 Issue 即可让团队知道该项已处理。

小技巧：在 PR 描述中使用 Closes #<issue-number>（例如 Closes #42）可以在合并 PR 时自动关闭对应的 Issue。

创建你的第一个 GitHub Project

#

Project 是把 Issue 以看板、表格或自定义视图组织起来的工具。以下为新建 Project 看板（以 Kanban 模板为例）的步骤：

1. 打开示例仓库或你的仓库（同上链接）。
2. 点击页面上方的 Projects 标签。
3. 右上角点击绿色 New project 按钮。
4. 在弹窗中选择 Kanban 模板作为起点。
5. 在 “Project name” 中输入项目名称。
6. 取消勾选 “Bulk import items”（如果不需要批量导入）。
7. 点击 Create project。

GitHub 会生成一个默认看板并自动创建几列（如 To do / In progress / Done），你可以按需编辑列与卡片。

项目页面上方有几个重要功能：

• Settings（设置）：管理访问权限、字段、描述、README、可见性、复制项目等。
• Insights（洞察 / 图表）：可以查看并自定义图表来监控进度、瓶颈等。
• Workflows（工作流）：配置基于事件的自动化（例如：当 Issue 加入项目时设为 todo；当 Issue 关闭时设为 Done；根据状态自动关闭 Issue 等）。
• Add status update（添加状态更新）：用于发布项目健康度或阶段性报告。

自定义字段（Custom fields）和图表能让你的 Project 更贴合团队流程与决策需求。

将 Issues 与 Projects 连接起来

#

把 Issue 作为卡片添加到 Project 后，它们会保持同步：在 Issue 中更改状态会反映到 Project 卡片上，反之亦然。

如何把现有 Issue 加入 Project：

1. 打开你的 Project 看板。
2. 底部点击 Add item。
3. 点击加号图标并选择 Add item from repository。
4. 勾选要加入的 Issue（可用顶端复选框一次全选）。
5. 点击 Add selected items，Issue 会作为卡片出现在看板上。

你可以拖拽卡片在不同列间移动来表示进度，或点击卡片查看完整 Issue 详情并在右侧编辑 Assignees、Labels 等字段。

重要的一点是：Issue 与 Project 是双向同步的，改变任一侧都会更新另一侧，从而保持项目状态一致。

端到端工作流示范

#

下面是一个简单的从创建 Issue 到合并 PR、自动关闭 Issue 的完整流程示例：

1. 打开 Project 看板，点击某列底部的 Add item。
2. 点击加号并选择 Create new issue。
3. 输入标题与描述，描述要包含预期行为及验收标准。
4. 点击 Create，Issue 会自动被加入到当前 Project。
5. 在 Issue 中选择 Labels，例如选择 enhancement。
6. 打开该 Issue，右侧设置 Assignee（指派负责人）。
7. 团队在 Issue 下添加评论以沟通进度或需求变更。
8. 当开始开发时，创建 Pull Request；在 PR 描述中引用并关闭 Issue：例如输入 Closes #<issue-number>（示例： Closes #12）。
9. 合并 PR 后，GitHub 会自动关闭对应的 Issue；Project 中的卡片状态也会自动更新为 Done（如果你配置了相关工作流）。

这个流程能显著减少频繁的状态会议，因为所有信息（讨论、代码、验收）都集中在 Issue 与 Project 中。

进阶与资源

#

• 视频教学（原文视频）：https://youtu.be/c67GaAkf1BE
• GitHub Issues 文档：https://docs.github.com/issues/tracking-your-work-with-issues/learning-about-issues/about-issues?utm_source=blog-episode-1&utm_medium=blog&utm_campaign=gfb-s3-2026
• GitHub Projects 文档：https://docs.github.com/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects?utm_source=blog-episode-1&utm_medium=blog&utm_campaign=gfb-s3-2026

实用建议：

#

• 从简单的标签与几个列开始，随着团队熟悉再逐步增加自定义字段与自动化。
• 在 Issue 模板中定义描述规范（复现步骤、预期行为、测试方法），能提升修复效率。
• 使用 Closes #<number> 在 PR 中自动关联并关闭 Issue，保证变更与任务记录一致。