GitHub 从入门到进阶完整教程

GitHub 是全球最大的基于 Git 的代码托管与协作平台，本教程从基础概念、环境搭建、核心操作到团队协作，循序渐进带你掌握 GitHub 完整使用流程。

一、基础概念：Git 与 GitHub

1. 核心区别

• Git：一款开源的分布式版本控制系统，安装在本地电脑上，用于管理代码的版本历史、分支切换、内容追溯。
• GitHub：基于 Git 的远程代码托管平台，提供云端仓库存储，同时支持团队协作、代码评审、开源社区等功能。

2. 核心术语

二、环境准备：账号与工具安装

1. 注册 GitHub 账号

1. 访问 GitHub 官网
2. 填写用户名、邮箱、密码完成注册
3. 验证邮箱后即可使用基础功能

2. 安装 Git 客户端

Git 是本地操作的核心工具，必须先安装：

• Windows：前往 Git 官网 下载安装包，默认配置一路下一步即可
• Mac：终端执行xcode-select --install自动安装，或通过官网下载
• Linux（Ubuntu/Debian）：终端执行sudo apt install git

安装完成后，打开终端/ Git Bash，执行以下命令验证安装：

git--version

输出版本号即安装成功。

3. 配置 Git 全局信息

设置你的用户名和邮箱，用于标记提交者身份：

# 配置用户名（建议和 GitHub 用户名一致）gitconfig--globaluser.name"你的GitHub用户名"# 配置邮箱（使用 GitHub 注册邮箱）gitconfig--globaluser.email"你的注册邮箱"# 查看配置是否生效gitconfig--list

4. 配置 SSH 密钥（免密登录，推荐）

SSH 密钥可以让你本地推送代码时无需重复输入账号密码，是开发者标配：

1. 生成密钥对

   ssh-keygen-ted25519-C"你的注册邮箱"

   连续按三次回车（默认路径、无密码）即可生成。

2. 查看公钥内容

   • Windows：cat ~/.ssh/id_ed25519.pub
   • Mac/Linux：cat ~/.ssh/id_ed25519.pub
     复制输出的全部内容。

3. 添加到 GitHub
   打开 GitHub → 右上角头像 →Settings→ 左侧SSH and GPG keys→ 点击New SSH key

   • Title 随便填（比如“家用电脑”）
   • Key 粘贴刚才复制的公钥内容
   • 点击Add SSH key完成

4. 测试连接
   终端执行：

   ssh-Tgit@github.com

   出现Hi 用户名! You've successfully authenticated即配置成功。

三、入门核心：仓库基础操作

场景1：克隆远程仓库到本地（最常用）

当 GitHub 上已有项目，你想下载到本地修改：

1. 打开目标 GitHub 仓库，点击绿色Code按钮，选择 SSH 地址并复制
2. 终端进入你想存放项目的文件夹，执行克隆命令：

   gitclone git@github.com:用户名/仓库名.git

3. 克隆完成后，进入项目目录即可开始修改代码。

场景2：本地项目关联 GitHub 远程仓库

本地已有代码，想上传到 GitHub 新建的空仓库：

1. 在 GitHub 上新建仓库：右上角+→New repository，填写仓库名，不要勾选初始化选项
2. 终端进入本地项目文件夹，初始化本地 Git 仓库：

   gitinit

3. 关联远程仓库（地址替换为你新建的仓库 SSH 地址）：

   gitremoteaddorigin git@github.com:用户名/仓库名.git

4. 后续执行提交、推送操作即可。

核心提交流程（必记）

修改代码后，从本地到远程的标准三步操作：

# 1. 将修改添加到暂存区（. 代表所有修改文件，也可指定文件名）gitadd.# 2. 提交到本地仓库，双引号内写本次修改的说明gitcommit-m"feat: 新增用户登录功能"# 3. 推送到远程仓库的 main 分支# 首次推送加 -u 关联分支，后续直接 git push 即可gitpush-uorigin main

其他高频基础命令

# 查看当前仓库状态（哪些文件修改了、哪些在暂存区）gitstatus# 查看具体修改了什么内容gitdiff# 查看提交历史（按 q 退出）gitlog# 拉取远程仓库的最新更新（别人提交了代码，你本地同步）gitpull# 查看当前关联的远程仓库地址gitremote-v

四、核心能力：分支管理

分支是 Git 的灵魂，支持多人并行开发、功能隔离，保证主分支代码稳定。

常用分支命令

# 查看所有本地分支，带 * 的是当前分支gitbranch# 创建新分支（不会自动切换）gitbranch 分支名# 切换到指定分支gitswitch 分支名# 或旧版写法gitcheckout 分支名# 创建并切换到新分支（最常用）gitswitch-c分支名# 或旧版写法gitcheckout-b分支名# 合并指定分支到当前分支（比如在 main 分支执行，合并 dev 分支）gitmerge dev# 删除本地分支（合并完成后清理）gitbranch-d分支名# 删除远程分支gitpush origin--delete分支名

分支开发标准流程

1. 从主分支main创建开发分支：git switch -c dev-login
2. 在新分支上编写代码、提交修改
3. 开发完成后，切换回主分支：git switch main
4. 先拉取主分支最新代码：git pull
5. 合并开发分支到主分支：git merge dev-login
6. 推送主分支到远程：git push

解决代码冲突

当两个分支修改了同一文件的同一行，合并时会触发冲突，需要手动解决：

1. 执行 merge 后，终端提示CONFLICT，执行git status找到冲突文件
2. 打开冲突文件，会看到如下标记：

   <<<<<<< HEAD （当前分支的代码） 主分支的代码内容 ======= 待合并分支的代码内容 >>>>>>> dev-login

3. 手动编辑文件，保留需要的代码，删除<<<<<<<=======>>>>>>>标记
4. 保存后重新暂存、提交，冲突即解决：

   gitadd.gitcommit-m"fix: 合并冲突"

五、团队协作：Fork + Pull Request 工作流

这是开源项目和多人团队最主流的协作方式，核心是“先提交申请，审核后再合并”。

完整协作流程

1. Fork 目标仓库
   打开别人的项目仓库，点击右上角Fork按钮，将仓库复制到你自己的 GitHub 账号下。

2. 克隆你自己的仓库
   从你的账号下，克隆 Fork 后的仓库到本地：

   gitclone git@github.com:你的用户名/仓库名.git

3. 创建开发分支
   不要直接在 main 分支修改，新建功能分支开发：

   gitswitch-cfix-bug-xxx

4. 提交并推送
   修改代码后，提交并推送到你自己的远程仓库：

   gitadd.gitcommit-m"fix: 修复xxxbug"gitpush origin fix-bug-xxx

5. 发起 Pull Request（PR）
   回到你的 GitHub 仓库页面，会自动出现Compare & pull request按钮，点击后：

   • 填写 PR 标题和详细说明（描述你做了什么修改）
   • 确认目标仓库是原作者的仓库，目标分支是main
   • 点击Create pull request提交

6. 代码评审与合并
   原仓库维护者会审核你的代码，可能提出修改意见。审核通过后，会点击合并按钮，你的代码就会进入原项目主分支。

同步原仓库更新

原仓库有新代码提交后，需要同步到你本地的仓库：

# 1. 添加原仓库为上游远程（只需要执行一次）gitremoteaddupstream git@github.com:原作者用户名/仓库名.git# 2. 拉取上游仓库的最新代码gitfetch upstream# 3. 切换到本地 main 分支，合并上游更新gitswitch maingitmerge upstream/main# 4. 推送到你自己的远程仓库gitpush

六、GitHub 常用功能

1. Issues：用于提交 Bug、功能建议、任务讨论，是项目协作的沟通工具
2. Wiki：用于存放项目文档、使用教程、架构说明
3. Releases：发布正式版本，可打包安装包、标注更新日志
4. GitHub Pages：免费托管静态网站，可用于搭建个人博客、项目文档站
5. Actions：自动化流水线工具，可实现自动测试、自动部署（CI/CD）
6. Star / Watch / Fork
   • Star：收藏项目
   • Watch：关注项目动态，有更新会收到通知
   • Fork：复制项目到自己账号下

七、进阶技巧

1. .gitignore 文件

在仓库根目录创建.gitignore文件，指定不需要被 Git 追踪的文件（比如依赖包、环境变量、编译产物），示例：

# 依赖目录 node_modules .vendor # 环境变量 .env .env.local # IDE 配置 .idea .vscode # 系统文件 .DS_Store Thumbs.db

2. 版本回退

提交错误想回到之前的版本：

# 先查看提交历史，复制要回退的 commit IDgitlog# 硬回退（会丢弃回退点之后的所有修改，谨慎使用）gitreset--hard提交ID

3. 临时暂存工作区

写到一半需要切换分支，但代码还没写完不想提交：

# 暂存当前工作区修改gitstash# 切换分支做完其他事，回来后恢复暂存内容gitstash pop

4. 标签（Tag）

用于标记重要版本节点，比如正式发布版本：

# 创建本地标签gittag v1.0.0# 推送标签到远程gitpush origin--tags

八、最佳实践与常见问题

开发规范

1. 提交信息规范：采用类型: 描述格式，比如
   • feat: 新增注册接口（新功能）
   • fix: 修复登录超时bug（修复问题）
   • docs: 更新README文档（文档修改）
   • style: 调整代码格式（代码样式调整）
2. 小步提交：不要攒一大堆修改再提交，每个功能点单独提交，方便回溯
3. 主分支保持可用：永远不在 main 分支直接开发，所有功能在分支完成后再合并
4. 推送前先拉取：git push前先执行git pull，减少远程冲突

常见问题

• push 被拒绝：大概率是远程有新代码你本地没有，先执行git pull同步后再推送
• 权限 denied：检查 SSH 密钥是否配置正确，是否有该仓库的推送权限
• 不知道怎么撤销修改：
  • 工作区修改未 add：git checkout 文件名撤销修改
  • 已 add 未 commit：git reset HEAD 文件名撤回暂存

附件一：Git 高频命令速查表

Git 高频命令速查表

一、配置与初始化

二、暂存与提交

三、分支管理

四、远程仓库操作

五、撤销与回退

六、临时暂存（Stash）

七、标签（Tag）

GitHub 三大核心工作流速记

1. 克隆开发流（已有远程仓库）

git clone 地址 → 改代码 → git add . → git commit -m "说明" → git push

2. 本地项目上传流（本地代码 → 新仓库）

GitHub 新建空仓库 → 本地 git init → git add . → git commit → git remote add origin 地址 → git push -u origin main

3. Fork + PR 协作流（参与开源/他人项目）

Fork 原仓库 → 克隆自己的仓库 → 新建分支开发 → 推送自己的仓库 → GitHub 页面发起 Pull Request → 等待原作者审核合并

同步原仓库更新：

git remote add upstream 原仓库地址（仅一次） → git fetch upstream → git switch main → git merge upstream/main → git push

附件二：GitHub Pages 搭建静态网站

GitHub Pages 是 GitHub 提供的免费静态网站托管服务，可直接托管 HTML/CSS/JS 静态资源，适合搭建个人博客、项目文档、演示站点。

1. 站点类型

GitHub Pages 分为两类，区别仅在于仓库命名和访问地址：

• 项目站点：依附于任意普通仓库，访问地址：https://你的用户名.github.io/仓库名/
• 用户/组织站点：仓库名必须为你的用户名.github.io，访问地址：https://你的用户名.github.io/（一个账号只能有一个）

2. 最简搭建：纯 HTML 项目站点

无需任何构建工具，3 分钟即可上线。

步骤 1：准备仓库与页面

1. 在 GitHub 新建一个仓库（或使用已有仓库），比如命名为my-demo-site
2. 在仓库根目录新建index.html，写入简单的网页内容：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>我的GitHub Pages站点</title> </head> <body> <h1>Hello GitHub Pages!</h1> <p>这是我的第一个静态网站。</p> </body> </html>

3. 提交并推送到远程main分支。

步骤 2：开启 Pages 服务

1. 进入仓库页面，点击顶部Settings
2. 左侧菜单找到Pages（在 Code and automation 分类下）
3. Build and deployment→Source选择Deploy from a branch
4. Branch 选择：main分支，文件夹选择/ (root)，点击Save
5. 等待 1-2 分钟，刷新页面即可看到生成的站点地址

步骤 3：访问验证

打开https://你的用户名.github.io/my-demo-site/，即可看到你的网页。

3. 个人主页站点（username.github.io）

搭建方式和上面完全一致，只有两点不同：

1. 仓库名必须严格为你的用户名.github.io（比如zhangsan.github.io）
2. 访问地址直接是https://你的用户名.github.io/，没有后缀路径

4. 进阶：绑定自定义域名

如果你有自己的域名，可以替换默认的 github.io 地址：

1. 在仓库根目录新建CNAME文件（全大写，无后缀），内容只写你的域名，例如：www.example.com
2. 提交推送到远程
3. 去你的域名服务商后台，添加 DNS 解析：
   • 若用子域名（如 www）：添加 CNAME 记录，指向你的用户名.github.io
   • 若用根域名：添加 A 记录，指向 GitHub Pages 官方最新 IP 地址
4. 回到仓库 Pages 设置页，勾选Enforce HTTPS开启强制 HTTPS

5. 常用静态生成器

GitHub Pages 原生支持静态站点生成工具，常见的有：

• Jekyll（GitHub 官方原生支持，无需额外配置）
• Hexo、Hugo、VitePress、Docsify 等（需配合 GitHub Actions 自动构建部署）

附件三：GitHub Actions 自动化部署实战

GitHub Actions 是 GitHub 内置的 CI/CD 自动化工具，可以在你提交代码后，自动执行构建、测试、部署等流程。

1. 核心概念

• Workflow（工作流）：一个完整的自动化流程，对应一个.yml配置文件
• Job（作业）：工作流中的一个执行单元，包含多个步骤
• Step（步骤）：具体执行的命令或动作
• Runner（运行器）：执行任务的服务器，GitHub 提供免费的 Ubuntu/Windows/macOS 运行环境

工作流文件必须放在仓库的.github/workflows/目录下。

2. 实战：前端项目自动构建部署到 Pages

以 Vite 构建的 Vue/React 项目为例，实现「提交代码 → 自动构建 → 自动部署到 GitHub Pages」全流程。

前置条件

• 项目是需要构建的前端工程（有 package.json，执行npm run build会生成dist目录）
• 仓库已推送到 GitHub

步骤 1：修改 Pages 部署源

1. 进入仓库 Settings → Pages
2. Source从「Deploy from a branch」改为GitHub Actions，保存

步骤 2：创建工作流配置文件

在项目根目录创建路径：.github/workflows/deploy-pages.yml，写入以下配置：

# 工作流名称 name: 部署到 GitHub Pages # 触发条件：推送到 main 分支时自动执行 on: push: branches: - main # 支持手动触发 workflow_dispatch: # 设置权限，允许部署 Pages permissions: contents: read pages: write id-token: write # 确保只有一个并发部署 concurrency: group: "pages" cancel-in-progress: false jobs: # 1. 构建任务 build: runs-on: ubuntu-latest steps: - name: 检出代码 uses: actions/checkout@v4 - name: 安装 Node.js uses: actions/setup-node@v4 with: node-version: 20 cache: 'npm' - name: 安装依赖 run: npm ci - name: 构建项目 run: npm run build - name: 上传构建产物 uses: actions/upload-pages-artifact@v3 with: path: ./dist # 2. 部署任务 deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: 部署到 GitHub Pages id: deployment uses: actions/deploy-pages@v4

步骤 3：项目路径适配（项目站点必做）

如果是项目站点（地址带/仓库名后缀），需要在构建配置中添加基础路径，否则静态资源会 404。

以 Vite 项目为例，修改vite.config.js，添加base配置：

export default { // 替换为你的仓库名，前后都要有斜杠 base: '/你的仓库名/', // 其他配置... }

如果是用户站点（username.github.io），则无需修改。

步骤 4：提交并触发自动部署

将工作流文件和配置修改提交，推送到main分支：

git add . git commit -m "feat: 添加自动部署工作流" git push

3. 查看运行状态

1. 进入仓库页面，点击顶部Actions标签
2. 可以看到正在运行或已完成的工作流
3. 点击对应工作流可查看详细执行日志，失败时可根据报错排查问题

部署成功后，即可通过 Pages 地址访问你的网站，后续每次提交代码到 main 分支，都会自动触发重新构建部署。

4. 其他常用场景

• 自动运行测试：在 build 步骤中添加npm run test，实现提交代码自动跑单测
• 多环境部署：区分开发环境、生产环境，推送到不同分支触发不同部署
• 发布 npm 包：打 tag 时自动发布到 npm 仓库