企业官网建设流程全解析

简介：面向GitHub初学者的PDF操作指南，旨在帮助开发者快速理解这一领先的代码托管与协作平台，掌握用Git进行版本控制和团队开发的基础方法。压缩包内为1个PDF文件，整包容量仅91KB，轻量便携，方便随时查阅。教程以清晰的分步讲解，系统覆盖了从创建账户、新建仓库、克隆项目，到提交更改、创建分支、合并请求的完整流程，并说明了如何通过Issue跟踪问题和展开团队讨论，以及参与开源项目贡献的具体方式。读者可以借助这些操作在云端备份代码、维护版本历史、与同伴协同修改，避免文件混乱和冲突，也能根据公共仓库和私有仓库的特点选择合适的管理策略。目前已有3458人学习，适合正在入门Git/GitHub、希望规范代码管理习惯的开发者。

1. GitHub 使用教程 PDF：一份能离线查、照着敲就能跑通的实战手册

GitHub 是今天开发者绕不开的平台，但很多人第一次打开它时是懵的：满屏英文、一堆按钮、clone 和 push 也不知道会不会覆盖别人代码。教程 PDF 的形式正好解决两个最实际的需求：一是能离线随时查，不用每次卡在网页加载上；二是从建仓库到提 Pull Request 有一条完整的操作链路，照着敲就行。这篇文章就把这条链路拆开讲清楚，适合刚接触 GitHub 的新手，也适合用过但没系统梳理过细节的开发者。你会发现，GitHub 真正值钱的不只是存代码，而是把「一个人写代码」变成「一群人协作」的那套流程。

2. 吃透 GitHub 的四个核心概念：仓库、分支、提交与 Pull Request

很多人卡在 GitHub 入门，不是因为命令记不住，而是脑子里没有建立模型。GitHub 上的一切操作，几乎都围绕仓库、分支、提交、Pull Request 这四个概念展开。先把它们的关系弄清楚，再记命令就顺了。

2.1 仓库与远端：先搞懂本地和 GitHub 上的双重存在

仓库（Repository）是一个项目的完整目录，包括源代码、文档、配置文件，以及 Git 自动记录的每一次修改历史。用 Git 在本地初始化一个目录后，这个目录就成了本地仓库；GitHub 上那个同名仓库则是远端仓库。日常开发中，绝大部分操作在本地完成，GitHub 承担的是备份、协作和发布入口的角色。

理解「本地和远端是两个独立副本」很重要。很多新手以为在 GitHub 网页上改个文件，本地就会自动同步，实际上两者不会自动通信，必须显式执行 push（推送本地到远端）或 pull（拉取远端到本地）。这个模型一旦建立，后面所有命令都有了解释框架。

# 查看当前项目的远端地址配置 git remote -v # 添加远端地址，origin 只是习惯命名，可以改 git remote add origin git@github.com:你的用户名/仓库名.git

git remote -v会输出两行，分别对应 fetch（拉取）和 push（推送）的地址。如果项目是从 GitHub 上 clone 下来的，这行命令会直接显示远端地址；如果是本地新建的仓库，则需要手动添加。origin是约定俗成的默认命名，不代表任何特殊含义，你也可以叫github，只是所有人都习惯用origin，保持惯例能省去协作时的沟通成本。

关于地址格式多说一句。https://github.com/用户名/仓库名.git和git@github.com:用户名/仓库名.git都能用。前者走 HTTPS 协议，推送时需要输入用户名和令牌（现在 GitHub 已不支持密码直接推送）；后者走 SSH 协议，只要配好密钥，推送全程无需重复认证。我的建议是新机器直接配 SSH，省掉后续认证的麻烦。

2.2 分支模型：从 main 拉出特性分支再合回去

分支是 Git 最聪明的设计。它相当于在某个提交点上切出一条平行线，你在分支上的操作不会影响主线（main），等代码稳定后再合并回去。团队协作的标准姿势是：每个人都从最新的 main 拉一条特性分支，各自开发，最后通过 Pull Request 审查合并。

# 切换到 main 分支并拉到最新 git checkout main git pull origin main # 从当前 main 创建并切换到一个新分支 git checkout -b feature/login # 查看当前所有分支，带 * 的是所在分支 git branch -a

git checkout -b feature/login是git branch feature/login和git checkout feature/login两步合并的简写，创建分支的同时切换过去。分支名的命名规范我一般建议用feature/（新功能）、fix/（缺陷修复）、docs/（文档）作为前缀，后面跟简短描述。这个约定让团队在查看分支列表时能一眼看出每条分支的意图。

分支模型的关键认知是：分支是轻量的，创建和删除几乎零成本。有些人习惯只在 main 上开发，或者开一个dev分支所有人往里堆代码，这在单人和小项目中能跑，但人一多就会互相踩踏。正确划分特性分支后，每个分支的提交历史相对独立，代码审查也有了明确范围。

2.3 提交与版本回退：commit、reset、revert 一次说清

提交（commit）是 Git 的核心操作，相当于给项目当前状态拍一张快照，并附上一段说明文字。每次提交有唯一的 SHA-1 哈希值，可以随时回去查看或恢复。这条时间线就是所谓的「后悔药」：只要提交过，就没有真正丢失的东西。

新手容易把reset和revert搞混。两者都能撤销变更，但作用方式完全不同。reset是移动分支指针，改写提交历史；revert是创建一个新的反向提交，保留原有历史。选哪个看场景：本地还没推送的提交，用reset随便折腾；已经推送到远端并且可能被同事拉取过的提交，必须用revert。

# 查看最近 5 条提交记录，一行一条 git log --oneline -5 # 回退到某次提交，但保留工作区改动 git reset --soft HEAD~1 # 生成一条反向提交，撤销指定提交的改动 git revert 7a9f3c2

HEAD~1表示当前提交的父提交，也就是最近一次提交往前一个。git reset --soft之后，改动会回到暂存区，你可以重新组织提交；如果想连工作区改动一起放弃，用--hard，但这一步没有确认提示，一旦执行，未提交的改动直接消失。所以我的习惯是：能用revert就优先revert，只在本地分支上才用reset --hard。

2.4 Pull Request：代码审查从不是可选项

Pull Request（PR）是 GitHub 协作的枢纽。它本质上是一个「请求」：请仓库维护者把你的分支合并进目标分支。但它的价值远不止合并动作，它同时提供了代码对比、逐行评论、自动化检查和讨论区。很多团队把 PR 当作代码评审的正式环节，没有第二个人的批准，代码不允许合并进 main。

PR 的运作逻辑是：你推送分支到 GitHub 后，在网页上点击「Compare & pull request」，填写标题和描述，指定审查者，然后等待反馈。审查者可以在具体某一行代码下留言，你也可以继续推送新提交到该分支，PR 会自动更新对比内容，不需要重建 PR。

正因为 PR 把代码变更变成了可讨论的对象，它才是质量控管的真正抓手。单人项目可能觉得 PR 多余，但只要是多人协作，哪怕是两个人，也值得走一遍 PR 流程。被审查时丢脸的地方，总比合并后线上故障要体面得多。

3. 从 0 到 1 跑通 GitHub 工作流：环境配置、推送与 PR 实操

概念模型建立之后，剩下的就是动手。这一章从一台干净的电脑开始，完整走一遍 GitHub 工作流：装 Git、配 SSH、建仓库、推代码、提 PR、合并。每一步都附命令和参数说明，照着敲即可。

3.1 环境准备：安装 Git、配置身份并校验 SSH 连通性

Git 的安装方式因系统而异，安装完成后第一件事是配置全局身份。这个身份信息会写进每一次提交记录里，所以要用真实常用的名字和邮箱，别人通过提交记录能找到你。

# 配置提交者姓名和邮箱，--global 表示对当前用户全局生效 git config --global user.name "你的名字" git config --global user.email "你的邮箱" # 生成 SSH 密钥对，指定 ed25519 算法和注释邮箱 ssh-keygen -t ed25519 -C "你的邮箱" # 查看公钥内容，复制后粘贴到 GitHub 的 SSH keys 设置页 cat ~/.ssh/id_ed25519.pub

ssh-keygen会询问保存路径和口令，直接回车用默认路径即可；口令（passphrase）可以留空，也可以设置一个，设置了的话每次 SSH 操作都要输入，嫌麻烦就用ssh-agent缓存。ed25519是目前推荐的算法，比传统的 RSA 更短更安全；如果用的系统比较老不支持，才退回到-t rsa -b 4096。

配置完成后，用一条命令验证连通性：

# 测试 SSH 连接，首次会提示确认指纹，输入 yes 即可 ssh -T git@github.com

看到类似「Hi 用户名! You've successfully authenticated"的提示就算通了。注意这条输出里可能出现一些与账户相关的信息，那是 GitHub 正常返回的认证确认，不用紧张。如果卡在这里，先检查公钥有没有完整粘贴、有没有复制到换行符，这是最常见的翻车点。

3.2 把本地项目推到 GitHub：初始化、关联远端与第一次 push

本地项目推到 GitHub，核心步骤是四件事：初始化本地仓库、生成第一次提交、创建远端仓库、关联并推送。其中创建远端仓库这一步在网页上操作更快，进入 GitHub 首页点「New repository」，填名字和描述，不要勾选「Add a README file」，保持空仓库状态，这样本地推送时不会有合并冲突。

# 在项目根目录初始化 Git 仓库 git init # 把所有改动加入暂存区，. 表示当前目录所有文件 git add . # 生成第一次提交，-m 后面是提交说明 git commit -m "init: 初始化项目" # 把默认分支名改为 main，GitHub 的默认分支现在是 main git branch -M main # 关联远端地址，使用 SSH 格式 git remote add origin git@github.com:你的用户名/仓库名.git # 首次推送，-u 建立本地分支与远端分支的追踪关系 git push -u origin main

git add .会把当前目录下所有未被忽略的文件加入暂存区。如果项目里有 node_modules、构建产物之类不该入库的文件，必须提前创建.gitignore文件，否则会把大量垃圾文件推上去。git branch -M main这条命令是应对 Git 旧版本默认分支名为master的情况，-M表示强制重命名。-u参数建立追踪关系后，之后在这条分支上直接敲git push即可，不用每次指定远端和分支名。

第一次推送成功后，一个容易忽略的细节是：远端仓库是否设置了权限保护。如果团队只有你一个人，无所谓；如果以后要多人协作，建议在 GitHub 仓库设置里把 main 分支设为受保护，禁止直接推送，所有变更必须走 PR。这个设置能极大降低误操作风险。

3.3 发起 Pull Request：分支命名、提交规范与 gh 命令

一个规范的 PR，从分支命名就开始了。分支名要能说明意图，提交信息要能讲清改动。我习惯在提交信息里用前缀区分类型：feat:表示新功能，fix:表示修 bug，refactor:表示重构，docs:表示文档改动。这个约定不是 GitHub 强制的，但配合 PR 模板使用，能大幅度提高审查效率。

# 确保 main 是最新的，再拉出特性分支 git checkout main git pull origin main git checkout -b feature/login-page # 开发完成后，查看改动内容是否正确 git status git diff --stat # 提交并推送到远端同名分支 git add . git commit -m "feat: 新增登录页及表单校验" git push -u origin feature/login-page

git status显示工作区、暂存区的状态，git diff --stat只显示文件改动统计而不展开具体内容，适合提交前快速检查。推送成功后，可以用 GitHub 网页端发起 PR，也可以安装 GitHub CLI（gh）在命令行完成整个流程。命令行方式对习惯终端操作的人更高效：

# 创建 PR，--base 指定目标分支，--head 指定来源分支 gh pr create --title "feat: 新增登录页" --body "实现说明：..." --base main --head feature/login-page # 查看当前仓库所有未合并的 PR 及状态 gh pr list # 查看某个 PR 的详细改动 gh pr view 12

gh pr create中--body是 PR 描述，建议写清楚改动动机、测试方法和影响范围，而不是只写一句「看代码」。--head指定来源分支，不传时默认使用当前所在分支。gh pr list输出会带 PR 编号、标题、分支和状态，编号在后续操作中会用到。gh 需要先执行gh auth login完成认证，它会引导你选择登录方式，整个过程在命令行里交互完成。

3.4 审查与合并：在命令行里完成一次完整的 code review

代码审查是需要具体动作的环节。审查者要做的不是泛泛地浏览，而是确认这几点：改动是否符合需求、有没有明显缺陷、测试覆盖是否到位、命名和风格是否与项目一致。GitHub 网页端的 PR 页面提供了很好的逐行评论体验，但命令行也能完成大部分工作流操作。

# 切换到一个 PR 对应的分支进行检查 git checkout feature/login-page # 查看该分支与 main 的具体差异 git diff main...feature/login-page # 合并 PR，--merge 表示生成合并提交，--delete-branch 合并后自动删除远程分支 gh pr merge 12 --merge --delete-branch

三点省略号main...feature/login-page表示「从 main 和该分支的共同祖先出发，到该分支为止的所有改动」，这是查看一个分支相对另一分支完整改动量的标准写法。gh pr merge有多种合并方式：--merge保留一条合并提交，--squash把该分支所有提交压缩成一条后再合并，--rebase将提交逐个重放到目标分支上保持线性历史。团队风格不同选择也不同，我倾向于用--squash，因为特性分支上的中间提交（wip、fix typo之类）往往没有保留价值，压缩成一条干净记录更利于追溯。

审查时如果发现问题，直接在网页端对应代码行下留言比命令行里写评论更直观。作者收到反馈后，在该分支上继续提交新改动并推送，PR 自动更新，审查者再次查看即可。这个过程会循环几轮，直到双方都满意才执行合并。

4. GitHub 使用避坑指南：认证、冲突与大文件的 5 个高频翻车点

GitHub 的命令本身不难，难的是各种边界情况。这一章整理了 5 个我在实际使用和教别人时反复遇到的翻车点，每条按现象、原因、解决的结构讲清楚，希望帮你少走弯路。

4.1 HTTPS 认证频繁失效：改用 SSH key 一次性解决

现象：使用 HTTPS 地址克隆仓库后，每次git push都提示输入用户名和密码，输入后依然报错，认证失败。有些开发者会以为是网络问题，反复重试浪费时间。

原因：GitHub 在 2021 年后已不再接受账户密码直接推送，必须使用个人访问令牌（Personal Access Token）代替密码。很多人不知道这一点，还在用旧习惯输入密码，自然被拒绝。另外，即便正确配置了令牌，HTTPS 方式依然会在凭据过期后再次弹出认证提示，操作体验很割裂。

解决：直接切换到 SSH 协议，一次性配置，长期免密。先按 3.1 生成密钥并把公钥添加到 GitHub 设置页，然后修改远端地址：

# 查看当前远端地址 git remote -v # 把 HTTPS 地址改成 SSH 格式 git remote set-url origin git@github.com:你的用户名/仓库名.git # 验证新地址是否生效 git remote -v

git remote set-url只修改当前仓库的远端地址，不影响其他仓库。改完后推送一次，如果提示确认主机指纹，输入yes即可。一个容易忽略的细节：如果本地有多个 GitHub 账号，需要配置~/.ssh/config文件为不同域名或别名指定不同密钥，否则 SSH 默认只会使用id_ed25519那一把。

4.2 冲突解决错误：把 rebase 和 merge 的语义混在一起

现象：分支合并时提示冲突，开发者先用git merge解决了一次，又对同一个分支执行git rebase，结果历史变得混乱不堪，PR 里出现大量重复提交。

原因：merge和rebase是两种不同的集成方式。merge保留两条分支的完整历史，产生一个合并提交；rebase把当前分支的提交「重放」到目标分支顶端，改写提交时间线。混用两者的结果往往是同一个改动被重复记录，且由于提交哈希变了，PR 的对比内容变得难以阅读。

解决：团队内约定一种主要方式，不要混用。我的建议是：本地分支开发时用rebase跟上远端变更，保持本地分支干净；推送到远端并发起 PR 后，合并阶段用squash或merge，不要在已推送的分支上再rebase。

# 拉取远端 main 的最新变更，并把当前分支的提交重放到其顶端 git pull origin main --rebase # 如果出现冲突，解决后继续 rebase git add . git rebase --continue # 觉得情况失控，立即中止并回到 rebase 前的状态 git rebase --abort

git pull --rebase和git pull的差别在于：后者默认会产生一个合并提交，前者保持线性历史。--continue在每次解决完冲突后执行，所有冲突都处理完才算完成；--abort是一键回到 rebase 之前的状态，用于发现自己处理不了冲突时。

4.3 大文件把仓库撑爆：Git LFS 要在一开始就规划

现象：项目里放进了一个几十 MB 的资源包或者数据集，提交推送都正常，但之后每次 clone 和 pull 都越来越慢，仓库体积直线上升，甚至达到 GitHub 单仓库推荐体积上限（1GB）而被警告。

原因：Git 的设计目标是文本和代码，它把每次提交的版本都完整存储。二进制大文件只要改动过一次，新旧两个版本都会留在历史记录里，无法通过简单删除当前文件来瘦身。这种问题一旦发生，清理成本非常高，涉及改写历史，还可能影响所有协作成员。

解决：从项目早期就引入 Git LFS（Large File Storage）。LFS 把大文件的内容存到独立存储中，仓库里只保留一个文本指针，clone 时按需拉取实际文件。这样既不影响 Git 历史上其他文件的轻量特性，也不会撑爆仓库。

# 安装 LFS 扩展，只需一次 git lfs install # 跟踪指定类型的文件，把匹配规则写入 .gitattributes git lfs track "*.psd" git lfs track "*.zip"

git lfs track的参数是文件路径模式，支持通配符。执行后生成的.gitattributes文件需要和代码一起提交到仓库，这样所有协作者自动应用同样的跟踪规则。关键原则是：LFS 要在文件第一次入库之前就配置好。如果已经把大文件推上去了，再启用 LFS 也不会自动迁移历史记录，需要额外执行迁移命令，而且过程复杂，所以趁早规划。

4.4 强制推送覆盖了同事提交：reflog 是最后的后悔药

现象：某人执行了git push --force，把本地旧历史强制推送到远端，结果同事刚推上去的提交全被覆盖。团队一瞬间「丢」了代码，群里一片混乱。

原因：--force的含义是「远端必须变成我本地这样」，Git 不做任何保护直接覆盖。很多时候并不是想覆盖别人，而是因为本地做了rebase导致提交历史与远端不一致，普通推送被拒，就顺手加了--force，却没意识到远端可能有别人新提交。

解决：优先用--force-with-lease代替--force。这个参数会在推送前检查远端是否已发生变化，如果远端有他人新提交，推送直接失败，而不是盲目覆盖。这是 Git 提供的安全网，应该成为习惯。

# 安全强制推送：远端有变化时拒绝推送 git push --force-with-lease # 如果不幸覆盖了同事提交，在本地找回对方提交的哈希 git reflog # 找到后创建一条分支指向那个提交，重新推送到远端恢复 git branch recover-branch 3f2a1c9 git push origin recover-branch

reflog记录了本地所有分支引用的变动史，即使提交被reset或rebase掉了，只要本地执行过，就一定能找到。git branch recover-branch 3f2a1c9中3f2a1c9是被覆盖提交的哈希，创建新分支后推送即可恢复。这套流程要求动作迅速，因为reflog默认只保留 90 天记录，且需要有人在本地留有过那个提交才行。

4.5 推送被拒 non-fast-forward：不是乱码，是远端领先于本地

现象：执行git push时看到错误信息! [rejected] ... (non-fast-forward)，很多新手以为是代码写错了，甚至有人直接删掉本地仓库重新 clone。

原因：这个提示只是说「远端有你本地没有的提交」，Git 为了防止覆盖他人代码而拒绝了这次推送。可能是同事推了新代码，也可能是你之前推送的一条分支被其他设备更新过。解决方案不是删仓库，而是先把远端变化拉下来整合。

解决：

# 先把远端 main 的变化拉下来并重放到本地提交之上 git pull origin main --rebase # 再尝试推送 git push origin main

--rebase在这里的作用是让本地提交「站在」远端最新提交之后，历史保持线性，不会产生多余的合并提交。如果拉取时发生冲突，按 4.2 的方法处理。这个流程多跑几次就熟了，遇到类似提示先别慌，Git 的报错大多数是保护性提示，不是灾难。

5. 把教程变成自己的 PDF 速查手册：整理、分类与持续更新

前面把 GitHub 的核心概念、完整工作流和高频踩坑点都过了一遍，但看过不算学会，真正能随时调用才算。最后一个建议是：把这些内容整理成一份属于你自己的速查手册，导出为 PDF，放在随手能打开的地方。整个过程分三步。

第一步，把命令按场景分类。我的习惯是在 Markdown 文件里建几个二级分类：仓库操作、分支操作、提交与回退、PR 相关、冲突处理、LFS 与仓库维护。每个分类下列出命令、参数含义、典型场景，以及这个命令容易踩的坑。不要贴大段解释，每行保持一两句话的长度，这样查的时候一眼能定位。

第二步，把踩坑记录做成独立清单。每次遇到问题并解决后，花 5 分钟把它追加到手册里，格式固定为「现象 → 原因 → 解决命令」。这些记录比任何教程都珍贵，因为它们是针对你自己项目、你自己容易犯的错定制的。过半年再回看这份清单，你会发现自己已经跨过了绝大多数低级错误。

第三步，导出 PDF 并持续迭代。多数 Markdown 编辑器或在线工具都支持导出 PDF，核心是排版清晰、代码和正文有明显区分。我习惯用支持自定义主题的编辑器，把代码块背景色调深、正文行距调大，导出效果接近印刷品。PDF 的好处是不依赖网络、不依赖特定软件，手机和电脑上都能直接打开。

我自己的这份手册已经积累了三年，从最初的三页基础命令，长到现在包含十几类操作、几十条踩坑记录。GitHub 的界面和命令会偶尔变动，但底层的 Git 模型很稳定，手册里的内容多半长期有效。如果发现某条命令在最新版本里行为变了，顺手记一笔更新，比四处搜索找答案效率高得多。

希望这份手册的思路，也能帮到你。

本文还有配套的精品资源，点击获取