跳到主要内容

github .github 目录介绍

· 阅读需 4 分钟
ahKevinXy
ahKevinXy
作者

.github 目录是 GitHub 平台专属的特殊目录，放置在代码仓库根目录下，用于配置 GitHub 平台的各类自动化、协作、展示规则。它是纯配置性目录，不影响代码逻辑，但能极大提升仓库的协作效率和展示效果。

下面按功能分类，把 .github 里最常用的文件/子目录讲清楚，新手也能直接套用。

一、核心目录结构（常用）​

.github/
├── ISSUE_TEMPLATE/       # 自定义 Issue 提交模板
├── PULL_REQUEST_TEMPLATE/ # 自定义 PR 提交模板
├── workflows/            # GitHub Actions 自动化工作流
├── CODEOWNERS            # 指定代码模块的负责人
├── CONTRIBUTING.md       # 贡献指南（可选，也可放根目录）
├── SUPPORT.md            # 支持/帮助说明
└── FUNDING.yml           # 捐赠/赞助配置

二、关键文件/目录详解​

1. .github/workflows/（最常用）​

  • 作用：存放 GitHub Actions 自动化脚本（YAML 格式），实现代码提交后自动编译、测试、部署、发布等。
  • 示例：一个简单的 Python 项目自动测试工作流（.github/workflows/ci.yml）：
name: 自动测试
on: [push, pull_request]  # 触发条件：推送代码/提交PR时
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - name: 安装依赖
        run: pip install pytest
      - name: 运行测试
        run: pytest test_*.py -v
  • 使用场景：自动部署网站、自动打包发布、自动代码检查、自动生成文档等。

2. .github/ISSUE_TEMPLATE/​

  • 作用：自定义 Issue 提交模板，规范用户/开发者提交 bug、需求的格式，避免信息不全。
  • 示例：创建 bug 报告模板（.github/ISSUE_TEMPLATE/bug_report.yml）：
name: Bug 报告
description: 提交你遇到的程序问题
labels: ["bug"]
body:
  - type: input
    id: version
    attributes:
      label: 版本号
      description: 你使用的程序版本
      placeholder: v1.0.0
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: 复现步骤
      description: 如何复现这个 bug
    validations:
      required: true
  • 效果：用户提交 Issue 时，会看到结构化的表单，而非空白输入框。

3. .github/PULL_REQUEST_TEMPLATE.md​

  • 作用：规范 PR（代码合并请求）的提交格式，让审核者快速了解修改内容。
  • 示例（.github/PULL_REQUEST_TEMPLATE.md）：
## 本次修改内容
- 修复了XX功能的bug
- 优化了XX接口的性能

## 测试情况
- [ ] 本地测试通过
- [ ] 新增单元测试

## 关联Issue
Closes #123（关闭编号123的Issue）

4. .github/CODEOWNERS​

  • 作用：指定代码仓库中不同目录/文件的负责人，当 PR 修改这些代码时，负责人会自动被要求审核。
  • 示例：
# 语法：路径 负责人（GitHub用户名/团队）
/src/backend/   @zhangsan @lisi  # backend目录由张三、李四审核
/tests/         @wangwu          # 测试目录由王五审核
*.py            @python-team     # 所有py文件由python-team团队审核

5. .github/FUNDING.yml​

  • 作用：配置仓库的赞助方式，GitHub 会在仓库页面显示“赞助”按钮。
  • 示例：
github: [你的GitHub用户名]  # GitHub Sponsors
patreon: 你的Patreon账号
open_collective: 你的OpenCollective项目
ko_fi: 你的Ko-fi账号

三、其他实用文件​

文件作用
.github/CONTRIBUTING.md告诉外部开发者如何参与项目贡献（如代码规范、PR流程）
.github/SUPPORT.md说明用户遇到问题时如何获取帮助（如联系方式、常见问题）
.github/SECURITY.md安全政策，如漏洞上报方式、支持的版本、修复周期

四、使用注意事项​

  1. .github 目录名必须小写，且以点开头，GitHub 才能识别；
  2. 所有配置文件修改后，直接提交到仓库即可生效，无需额外设置；
  3. 不同文件的语法需严格遵循 GitHub 规范（如 YAML 格式、路径匹配规则）；
  4. 这些配置仅对 GitHub 平台生效，其他 Git 托管平台（如 GitLab、Gitee）不识别（GitLab 对应 .gitlab/ 目录）。

总结​

  1. .github 是 GitHub 专属配置目录，核心用于自动化（Actions） 和协作规范（Issue/PR模板、CODEOWNERS）；
  2. 最核心的子目录是 workflows/（GitHub Actions），能实现代码提交后的自动化流程；
  3. 自定义 Issue/PR 模板、CODEOWNERS 可大幅提升团队协作效率，规范贡献流程。