GitHub 使用指南：从入门到精通

一、GitHub 简介

GitHub 是全球最大的代码托管平台之一，基于 Git 版本控制系统，为开发者提供代码存储、协作开发、项目管理等功能。截至目前，GitHub 已拥有超过 1 亿开发者用户，托管了超过 4 亿个仓库。

GitHub 能做什么？

  • 🗄️ 代码托管：安全存储代码，支持版本管理
  • 🤝 协作开发：多人共同编辑同一项目
  • 🔀 代码审查：通过 Pull Request 审查代码
  • 🐛 问题跟踪：使用 Issues 管理 Bug 和功能需求
  • ⚙️ CI/CD：自动化测试和部署
  • 📦 包管理：托管和分发软件包

二、核心概念

2.1 仓库（Repository）

仓库是存储项目代码的地方，分为：

类型 说明
Public（公开） 所有人可见，免费
Private（私有） 仅授权用户可见，需付费

2.2 Git 基本概念

1
工作目录 → 暂存区（Stage）→ 本地仓库 → 远程仓库
  • Working Directory（工作目录）：你正在编辑的文件
  • Stage（暂存区）：准备提交的文件集合
  • Local Repository（本地仓库）：本地的 Git 记录
  • Remote Repository（远程仓库）：GitHub 上的仓库

2.3 分支（Branch）

分支用于隔离开发主线，通常包括：

分支类型 命名规范 说明
主分支 main / master 稳定版本，生产环境
开发分支 develop / dev 开发中的代码
功能分支 feat/xxx 新功能开发
修复分支 fix/xxx Bug 修复
热修复分支 hotfix/xxx 紧急修复

三、Git 基础命令

3.1 初始配置

1
2
3
4
5
6
# 设置用户名和邮箱
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 查看配置
git config --list

3.2 克隆与远程

1
2
3
4
5
6
7
8
9
10
11
# 克隆远程仓库
git clone https://github.com/username/repo.git

# 添加远程仓库
git remote add origin https://github.com/username/repo.git

# 查看远程仓库
git remote -v

# 推送代码到远程
git push origin main

3.3 基础操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 查看当前状态
git status

# 查看文件变更
git diff

# 添加文件到暂存区
git add filename.txt      # 添加单个文件
git add .                 # 添加所有变更

# 提交到本地仓库
git commit -m "提交信息"

# 查看提交历史
git log
git log --oneline         # 简洁模式

# 拉取远程更新
git pull origin main

# 推送本地提交到远程
git push origin main

3.4 分支操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 查看本地分支
git branch

# 查看所有分支（包括远程）
git branch -a

# 创建新分支
git branch feature/new-feature

# 切换分支
git checkout feature/new-feature
# 或
git switch feature/new-feature

# 创建并切换（推荐）
git checkout -b feature/new-feature

# 删除本地分支
git branch -d feature/new-feature

# 强制删除本地分支
git branch -D feature/new-feature

# 重命名分支
git branch -m old-name new-name

3.5 撤销与回退

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 取消暂存（从暂存区移除）
git reset HEAD filename.txt

# 回退到上一个提交（保留工作目录）
git reset --soft HEAD^

# 回退到上一个提交（保留工作目录和暂存区）
git reset --mixed HEAD^

# 回退到上一个提交（丢弃所有变更，危险操作）
git reset --hard HEAD^

# 查看所有操作记录（用于恢复误删的提交）
git reflog

# 丢弃工作目录的修改（恢复文件）
git checkout -- filename.txt

四、GitHub 协作流程

4.1 Fork & Clone 工作流

当你需要参与别人的项目时：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. Fork 仓库（在 GitHub 网页上操作）

# 2. 克隆你 Fork 的仓库
git clone https://github.com/your-username/repo.git

# 3. 添加上游仓库（原始仓库）
git remote add upstream https://github.com/original-owner/repo.git

# 4. 保持与上游仓库同步
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

4.2 Pull Request 工作流

PR 是 GitHub 协作的核心，以下是完整流程：

Step 1：创建功能分支

1
2
3
4
5
6
# 确保在最新代码基础上创建
git checkout main
git pull origin main

# 创建并切换到新分支
git checkout -b feat/add-login-feature

Step 2：开发与提交

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 编辑代码...

# 查看变更
git status
git diff

# 暂存并提交
git add .
git commit -m "feat: add user login feature

- Add login API endpoint
- Add JWT token generation
- Add password validation
- Add unit tests"

Step 3：推送分支

1
2
# 首次推送（-u 设置上游分支）
git push -u origin feat/add-login-feature

Step 4：创建 Pull Request

在 GitHub 网页上点击 “Compare & pull request” 按钮，填写：

1
2
3
4
5
6
7
8
9
10
11
## Summary
简要描述这次变更

## Changes
- 具体变更列表

## Test Plan
- [ ] 测试用例通过
- [ ] 手动测试验证

Closes #issue_number

Step 5：代码审查与修改

1
2
3
4
5
6
7
8
9
10
11
12
# 获取最新代码（如果有新的提交）
git fetch origin

# 在当前分支上 rebase（整理提交历史）
git rebase origin/main

# 如果需要修改提交
git commit --amend        # 修改最后一次提交
git rebase -i HEAD~3      # 交互式修改前3次提交

# 强制推送（rebase 后需要）
git push --force-with-lease origin feat/add-login-feature

Step 6：合并与清理

1
2
3
4
5
6
7
8
# 合并 PR（通过 GitHub 网页或命令行）
# 在 GitHub 上点击 "Squash and merge"

# 删除已合并的分支
git checkout main
git pull origin main
git branch -d feat/add-login-feature
git push origin --delete feat/add-login-feature

4.3 提交信息规范

采用 Conventional Commits 规范：

1
2
3
4
5
<type>(<scope>): <subject>

<body>

<footer>

type 类型：

Type 说明
feat 新功能
fix Bug 修复
docs 文档更新
style 代码格式（不影响运行）
refactor 重构（不是新功能或修复）
perf 性能优化
test 测试相关
ci CI/CD 相关
chore 构建或辅助工具

示例：

1
2
3
4
5
6
7
feat(auth): add OAuth2 login support

- Add Google OAuth provider
- Add GitHub OAuth provider
- Add user profile linking

Closes #123

五、GitHub 进阶功能

5.1 Issues 管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 使用 gh CLI 创建 Issue
gh issue create \
  --title "Login fails with special characters" \
  --body "## Bug Description
描述 Bug...

## Steps to Reproduce
1. 步骤1
2. 步骤2

## Expected vs Actual
期望行为 vs 实际行为" \
  --label "bug" \
  --assignee username

5.2 GitHub Actions CI/CD

在 .github/workflows/ 目录下创建 YAML 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run tests
        run: npm test
        
      - name: Build
        run: npm run build

5.3 GitHub Pages 部署

  1. 进入仓库 Settings → Pages
  2. 选择 Source 分支
  3. 访问 https://username.github.io/repo

5.4 Wiki 文档

  • 在仓库页面点击 Wiki 标签
  • 可用 Markdown 编写文档
  • 适合项目使用说明

六、实用技巧

6.1 Git 别名

1
2
3
4
5
6
# 简化常用命令
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --all"

6.2 Git 忽略文件

创建 .gitignore 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 依赖
node_modules/
venv/

# 构建产物
dist/
build/

# 环境变量
.env

# IDE
.vscode/
.idea/

# 日志
*.log

# 系统文件
.DS_Store
Thumbs.db

6.3 清理远程已删除分支

1
2
3
4
5
# 同步分支列表
git fetch --prune

# 或设置自动清理
git config --global fetch.prune true

6.4 暂存工作区

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 暂存当前工作（不提交）
git stash

# 查看暂存列表
git stash list

# 恢复暂存内容
git stash pop

# 恢复特定暂存
git stash apply stash@{0}

# 清除暂存
git stash drop stash@{0}

6.5 标签管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建轻量标签
git tag v1.0.0

# 创建附注标签（推荐）
git tag -a v1.0.0 -m "Version 1.0.0"

# 推送标签到远程
git push origin v1.0.0

# 推送所有标签
git push origin --tags

# 查看标签
git tag -l

七、常见问题

Q1: 如何撤销已经 push 的提交？

1
2
3
4
5
# 创建新的提交来撤销之前的修改
git revert HEAD

# 推送撤销
git push origin main

Q2: 如何合并多个提交？

1
2
3
4
# 交互式 rebase 最近 3 个提交
git rebase -i HEAD~3

# 在打开的编辑器中，将第二个以后的 "pick" 改为 "squash" 或 "s"

Q3: 如何解决冲突？

1
2
3
4
5
6
7
8
# 拉取远程代码时出现冲突
git pull origin main

# 手动编辑冲突文件，删除 <<<<<<<, =======, >>>>>>> 标记
# 编辑后：
git add .
git commit -m "resolve merge conflicts"
git push origin main

Q4: 大文件上传失败？

GitHub 对单文件有 100MB 限制。可使用 Git LFS：

1
2
3
4
5
6
7
8
9
10
# 安装 Git LFS
git lfs install

# 跟踪大文件
git lfs track "*.zip"
git lfs track "*.psd"

# 正常提交即可
git add .
git commit -m "add large files"

八、常用工具

工具 说明
GitHub Desktop 图形化 Git 客户端
SourceTree Atlassian 出品的免费 Git 客户端
VS Code Git VS Code 内置 Git 功能
GitLens VS Code Git 扩展，增强代码历史查看
gh CLI GitHub 官方命令行工具

安装 gh CLI

1
2
3
4
5
6
7
8
# macOS
brew install gh

# Linux
sudo apt install gh

# 登录
gh auth login

九、总结

GitHub 是现代软件开发的必备工具，掌握以下核心技能：

技能 掌握程度
Git 基础命令 ✅ 必备
分支管理 ✅ 必备
Pull Request 流程 ✅ 必备
代码审查 🎯 进阶
GitHub Actions 🎯 进阶
多人协作 🎯 进阶

熟练使用 GitHub 能极大提升开发效率和团队协作能力，建议从日常小项目开始练习，逐步掌握高级功能。

💡 相关资源