GitHub 使用指南¶

GitHub 是全球最大的代码托管平台，也是开源社区的核心枢纽。除了存放代码，它还提供了项目管理、协作开发、自动化部署等一整套工具链。

1. 仓库基础操作 (Repository)¶

创建仓库¶

点击右上角 + → New repository
填写仓库名（建议用小写字母和短横线，如 my-project）
选择 Public（公开）或 Private（私有）
可选勾选 Add a README file（强烈建议勾上）
可选添加 .gitignore 模板和 License

常用仓库操作¶

操作	说明
Clone	把远程仓库下载到本地：`git clone https://github.com/用户名/仓库名.git`
Fork	把别人的仓库"复制"一份到你自己的账号下，你可以自由修改而不影响原仓库。
Star	给仓库"点赞收藏"，方便以后在你的 Stars 列表中找到。
Watch	关注仓库动态，有新 Issue、PR 等会收到通知。

2. SSH 密钥配置（免密推送）¶

每次 git push 都要输密码非常麻烦，配置 SSH 密钥后可以免密操作。

生成 SSH 密钥¶

# 生成密钥对（一路回车即可）
ssh-keygen -t ed25519 -C "your_email@example.com"

# 查看公钥内容
cat ~/.ssh/id_ed25519.pub

添加到 GitHub¶

复制上面输出的公钥内容（以 ssh-ed25519 开头的整行）
打开 GitHub → Settings → SSH and GPG keys → New SSH key
粘贴公钥，起个名字（如 "My Laptop"），保存

测试连接¶

ssh -T git@github.com
# 成功会显示：Hi 用户名! You've successfully authenticated...

切换仓库为 SSH 方式¶

# 查看当前远程地址
git remote -v

# 如果是 https:// 开头，改为 SSH 方式
git remote set-url origin git@github.com:用户名/仓库名.git

3. Pull Request（PR）协作流程¶

PR 是 GitHub 上多人协作的核心机制。当你想给一个项目贡献代码时，标准流程如下：

标准 PR 流程¶

1. Fork 原仓库到自己账号
2. Clone 到本地
3. 创建新分支：git switch -c feature/my-change
4. 修改代码并 commit
5. Push 到自己的 Fork：git push origin feature/my-change
6. 在 GitHub 上点击 "New Pull Request"
7. 等待维护者审查（Review）、合并（Merge）

PR 页面核心功能¶

功能	说明
Reviewers	指定谁来审查你的代码。
Assignees	指定谁负责处理这个 PR。
Labels	打标签分类，如 `bug`、`enhancement`、`documentation`。
Conversation	讨论区，可以针对具体代码行留评论。
Files changed	查看所有修改的文件差异（Diff）。
Checks	查看 CI/CD 自动化测试是否通过。

4. Issue 问题追踪¶

Issue 是 GitHub 的"任务清单"，用于追踪 Bug、提出新功能建议或记录待办事项。

创建 Issue 的最佳实践¶

标题简明扼要：如 "登录页面在 Safari 上样式错乱"
描述清晰：包含复现步骤、期望行为、实际行为
善用标签：bug、enhancement、question、good first issue
关联 PR：在 PR 描述中写 Closes #123，合并时会自动关闭对应 Issue

5. GitHub Actions（自动化 CI/CD）¶

GitHub Actions 是 GitHub 内置的自动化工具，可以在代码推送、PR 创建等事件触发时自动执行任务（如测试、构建、部署）。

工作流文件位置¶

项目根目录/
└── .github/
    └── workflows/
        └── ci.yml      # 工作流配置文件

一个基础示例：推送时自动运行测试¶

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest

核心概念¶

概念	说明
Workflow	一个完整的自动化流程，由 `.yml` 文件定义。
Event	触发工作流的事件，如 `push`、`pull_request`、`schedule`（定时）。
Job	工作流中的一个任务单元，多个 Job 默认并行执行。
Step	Job 中的每一步操作，可以是运行命令或使用别人写好的 Action。
Action	可复用的操作模块，Marketplace 上有大量现成的。

6. GitHub Pages（免费静态网站托管）¶

GitHub Pages 可以将仓库中的静态文件（HTML/CSS/JS 或 Markdown）直接发布为网站，非常适合个人博客、项目文档。

开启方式¶

进入仓库 → Settings → Pages
选择 Source：
- Deploy from a branch：选择分支（如 main）和目录（/ 或 /docs）
- GitHub Actions：使用自定义工作流部署（更灵活）
保存后等待几分钟，访问 https://用户名.github.io/仓库名/

自定义域名¶

在仓库根目录创建 CNAME 文件，内容为你的域名（如 blog.example.com）
在域名服务商处添加 DNS 记录：
- CNAME 记录：blog → 用户名.github.io
在 Pages 设置中勾选 Enforce HTTPS

7. 常用快捷键与技巧¶

键盘快捷键（在仓库页面按 `?` 可查看全部）¶

快捷键	功能
`.`	在当前仓库打开 Web 版 VS Code 编辑器（github.dev）
`t`	快速搜索文件名
`l`	跳转到指定行号
`b`	查看文件的 Blame（每行代码是谁写的）

实用技巧¶

技巧	说明
搜索代码	在仓库页面按 `/` 或使用顶部搜索栏，支持按语言、路径、文件名过滤。
引用代码行	点击代码行号高亮该行，URL 自动变为 `#L42`；按住 Shift 点击可选择范围 `#L42-L50`，适合分享给他人。
查看历史	在文件页面点击 History 查看该文件的所有修改记录。
对比分支	访问 `github.com/用户/仓库/compare/main...dev` 可直接对比两个分支差异。
快速编辑	在任何文件页面点击铅笔图标即可在线编辑，适合快速修改 typo。
下载单个文件	打开文件 → 点击 Raw → 右键另存为。

8. .gitignore 配置¶

.gitignore 文件告诉 Git 哪些文件不需要追踪（如编译产物、环境配置、密钥文件等）。

常用模板¶

# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
.venv/
.env

# Node.js
node_modules/
npm-debug.log

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# 密钥与敏感信息
*.pem
*.key
.env.local

💡 提示： GitHub 提供了各种语言/框架的 .gitignore 模板，创建仓库时可以直接选择。