简介这是一份面向初学者的GitHub操作指引以PDF文档形式系统梳理了从注册账户到协作开发的核心流程帮助不熟悉版本控制的开发者快速建立对代码托管与团队协作的整体认知。资源为单个PDF文件体积约91KB内容精炼、结构紧凑适合通勤或碎片时间随时查阅。文档按实际操作顺序介绍创建账户、新建仓库、克隆仓库、添加文件与提交更改、创建分支与合并、发起拉取请求等关键步骤每一步均配有清晰的界面操作说明与提交信息撰写建议能有效降低新手入门门槛。同时涉及问题跟踪、团队讨论与开源项目贡献方式覆盖日常开发中的高频使用场景。目前已有三千四百余人浏览学习对刚接触Git与GitHub的编程学习者、需要规范管理代码的高校学生以及中小团队开发者而言是一份便于快速上手的入门参考资料。1. GitHub 使用教程 PDF从“只会下载 ZIP”到“能提交代码”的完整路径很多人第一次接触 GitHub 时把它当成一个网盘打开仓库页面点绿色的 Code 按钮选 Download ZIP下载完就关掉页面。这种用法本身没有错但你在 GitHub 上获得的只是一份快照而不是一个可以持续提交、回滚、协作的代码仓库。这份 GitHub 使用教程 PDF 讲的就是从「注册账号」到「发起 Pull Request」的完整路径适合两类人一类是刚注册账号、还没成功推过一次代码的新手另一类是准备带团队统一 Git 工作流、需要一套可复制节奏的从业者。照着 PDF 的节奏走一遍你至少能把自己的项目干净地推上去也能看懂别人仓库里的分支和 PR 结构。它不教你写代码教的是代码怎么在 Git 世界里流动。2. 账号与仓库创建先跑通认证和令牌再谈上传2.1 GitHub 账号的二步验证与 Personal Access Token先解决“能不能登录”注册账号只是第一步真正让新手卡住的是认证环节。GitHub 早在 2021 年就停止支持用账户密码直接执行 Git 操作也就是说你git push的时候输入用户名加密码大概率会被拒绝。现在认证方式只剩两种Personal Access Token个人访问令牌和 SSH Key。如果你走 HTTPS 协议需要先生成 token。路径在 GitHub 页面右上角头像 → Settings → Developer settings → Personal access tokens → Fine-grained tokens。创建时建议勾选Contents: Read and write权限这样你才能推送代码到自己的仓库。不要嫌权限配置麻烦最小权限原则能防止 token 泄露后仓库被恶意清空。如果走 SSH 协议则需要生成密钥对并公钥上传到 GitHub。这是我推荐长期开发用的方式因为配置一次之后后续所有git push和git pull都不需要再输凭证。生成命令如下ssh-keygen -t ed25519 -C your_emailexample.com执行后按三次回车密钥默认生成在~/.ssh/id_ed25519和~/.ssh/id_ed25519.pub。私钥留在本机公钥内容粘贴到 GitHub 的 Settings → SSH and GPG keys → New SSH key 里。我一般会把公钥完整复制出来粘贴后立刻在终端验证ssh -T gitgithub.com看到Hi username! Youve successfully authenticated就说明通了。这里有两个细节经常踩坑一是-C参数后填邮箱只是给密钥做个注释填错了不影响实际认证二是生成时如果设置了 passphrase每次执行 Git 操作都会要求输入如果你不想配置 ssh-agent建议直接留空。HTTPS 加 token 和 SSH 两种方式我更推荐 SSH。token 有过期时间到期后忘了续期push 就会突然失败而 SSH 密钥只要不换电脑不删除基本一劳永逸。新手刚开始可能觉得配置密钥很麻烦但这一步做透了后面所有仓库操作都会顺畅很多。2.2 创建仓库可见性、README、.gitignore 一次选对登录后点击页面右上角的 号选择 New repository就进入了仓库创建页面。这里有一组选项PDF 里提了名字和描述但实际使用时还有三个关键决策可见性、README 初始化和 .gitignore 模板。可见性分 Public 和 Private。开源项目或需要对外展示的作品选 Public内部工具、公司项目、还不成熟的代码选 Private。这个选择后期可以改但仓库一旦公开再转私有历史里的敏感信息并不会自动消失所以建议开头就谨慎一点。初始化选项里有个容易被忽略的复选框Add a README file。新手通常直接勾上这本身没问题但我建议你了解它的副作用——如果你勾了 READMEGitHub 会先创建一个带提交历史的仓库然后你本地再git init时两边就出现了无关联历史第一次 push 会被拒绝需要先git pull合并。后面第三节会详细说处理办法。.gitignore 模板是很多人忽略但必须选的东西。按你的技术栈选择对应模板比如 Python 项目选 PythonNode 项目选 NodeGitHub 会自动生成一份规则文件把node_modules、__pycache__、.env这类不该提交的文件挡在仓库外。没有这份文件你很容易手一滑把依赖目录整包推上去仓库体积瞬间膨胀后面再清理就是血泪故事。2.3 真实场景从本地已有项目推送到 GitHub 的完整命令链创建完空仓库后页面会给出三种推送提示。但常见场景不是空仓库起步而是你本地已经有一个做了几天的项目现在想推上去。这种情况下推荐的命令链是这样的git init git add . git commit -m chore: init project git branch -M main git remote add origin gitgithub.com:yourname/yourrepo.git git push -u origin main逐行说明一下。git init在项目根目录初始化本地仓库git add .把所有文件加入暂存区这里有个隐患——如果没有 .gitignore你会把依赖目录也加进去所以执行前一定要确认.gitignore已存在。git commit创建首次提交消息用chore: init project表明这是项目初始化而不是功能提交。git branch -M main把当前分支重命名为 main因为 GitHub 默认主分支叫 main而老版本 Git 默认分支叫 master不统一后面会有麻烦。git remote add origin把本地仓库与远程仓库建立关联origin是远程仓库的默认别名。最后的git push -u origin main首次推送并建立追踪关系-u参数让后续直接输入git push就能推送到正确的分支。如果你在创建仓库时勾选了 READMEgit push前需要先合入远程历史git pull origin main --allow-unrelated-histories这个参数允许两个没有共同祖先的历史合并。合完后可能会产生冲突尤其是两边都有 README 时手动保留一份再提交即可。顺带说一个高频搜索词「github 怎么上传文件夹」。很多人习惯在 GitHub 网页端直接把文件夹拖进上传区小文件和少量文件这么操作没问题但文件夹里如果嵌套了.git目录、符号链接或者超大二进制文件网页上传很容易传一半失败或者把隐藏文件漏掉。命令行方式才是可靠路径这也是为什么我强调先把本地仓库跑通再谈上传。3. 克隆、提交与推送把本地文件变成远程可追踪的历史3.1 克隆方式怎么选HTTPS、SSH、GitHub CLI 的取舍从仓库页面的 Code 按钮下拉列表里你会看到三种获取仓库的方式HTTPS、SSH、GitHub CLI。很多人 downloads 完 ZIP 就以为拿到了代码其实 ZIP 只是当前文件的快照里面没有.git目录也就没有提交历史你改了代码也无法推回去。git clone则会把完整的仓库历史下载到本地这是参与开发的起点。三种方式的选择按场景区分即可。HTTPS 配合 token适合临时在一台不常用的机器上拉代码不用配置密钥但每次操作可能要输凭证SSH 适合自己的主力开发机配置一次长期免密GitHub CLI 适合已经安装了gh命令行工具的开发者它可以顺带完成登录、创建仓库、发起 PR 等操作省去在网页和终端之间来回切换。GitHub 上下载到的 ZIP 包解压后确实可以直接运行代码前提是项目依赖已经被作者打进包里。但绝大多数项目不会这么做正确姿势是克隆后先看 README 里的安装和启动说明。很多搜索「github 上的项目怎么运行」的人问题根源就是只拿了 ZIP没看仓库里的 README也没装依赖自然跑不起来。3.2 工作区、暂存区、本地仓库提交动作背后的三个抽屉Git 的提交链路常被讲成三个区域但真正落到命令上很多人还是分不清add和commit的区别。最直观的理解是工作区是你的磁盘文件改动了它暂存区是你挑选过的改动集合本地仓库是已经固化的历史记录。一次完整的修改提交推送流程如下git status git add index.html git commit -m feat: update homepage title git push先说git status。这是排查一切问题的第一工具它告诉你哪些文件被改过、哪些已经进入暂存区、当前在哪个分支。我见过不少人提交错文件就是因为跳过了这一步直接git add .把所有改动一股脑打包。正确习惯是执行git status看清单再精确指定文件git add index.html。git add只做一件事把文件从工作区复制到暂存区。它不产生历史记录只标记「这些改动是我准备提交的」。git commit才把暂存区的内容固化成一条永久历史记录。注意一个细节如果你改了文件但没有git add就执行git commitGit 只会提交上一次暂存的内容新改动不会进提交这解释了为什么很多人以为自己提交了所有改动推上去一看远程还是旧的。git push把本地仓库的提交上传到远程。远程仓库不会自动出现你本地的新提交每次都要显式推送。第一次推送某个分支时建议带上-u参数建立追踪关系之后就能直接git push不用每次写全命令。3.3 提交信息怎么写从一句话到团队模板提交信息是仓库历史里的「黑匣子」写得好不好直接影响三个月后你自己能不能看懂这段代码为什么存在。GitHub 官方推荐的格式是类型加简述常见类型如下类型适用场景示例feat新增功能feat: add login pagefix修复缺陷fix: resolve null pointer in parserdocs文档变更docs: update installation guiderefactor重构代码refactor: extract http clientchore构建、依赖等杂项chore: upgrade eslint单行提交信息适合简单改动但复杂改动建议多行描述。在终端里执行git commit -m feat: add login page -m 3rd party oauth integration with github可以写两行第一行是标题第二行是正文。团队协作时可以约定更完整的模板比如格式固定为「类型: 简述 空行 动机 影响范围」但那时通常会引入 commitlint 这类工具做自动化检查。提交频率上我的习惯是「一次提交只干一件事」。新增一个按钮是feat顺手改了样式应该拆成feat加style两次提交或者干脆分开提交。不要攒一周的改动一次性git add .那样提交信息写什么都含糊出问题回滚时也找不到精确节点。4. 分支与合并用隔离保障协作冲突处理是必修课4.1 分支的使用边界功能开发、紧急修复、实验性改动分支是 Git 隔离能力最直接的体现。主分支永远是稳定版本新功能开发、缺陷修复、实验性想法都在独立分支上进行测试通过后再合回来。这样做最大的好处是主分支随时保持可运行状态不会因为某个人开发到一半的代码而崩溃。什么时候该开分支我按项目阶段给你一个可参考的判断新增功能无论大小都开分支修复线上问题开分支尝试一种不确定的技术方案开分支并在分支名里标注 experimental改动文档、注释这类低风险内容可以直接在主分支提交但如果是团队协作仍然建议走分支因为主分支可能有保护规则不允许直接推送。分支命名建议带上类型和意图比如feat/login-page、fix/typo-in-readme、experiment/webassembly-bench。这样查看远程分支列表时一眼就能看出每个分支的用途不用逐个点开。创建并切换到新分支的命令git switch -c feat/login-page-c是 create 的缩写等价于先git branch feat/login-page再git switch feat/login-page。老版本 Git 用git checkout -b也能达到同样效果但git switch语义更清晰新项目建议直接习惯它。4.2 合并流程fast-forward 与三路合并的差异当你完成分支开发准备把改动合回主分支时执行git switch main git pull git merge feat/login-pagegit switch main切回主分支git pull把远程主分支的最新提交拉下来这一步很重要——如果不先同步你本地的 main 可能落后于远程合并时会产生意外的分叉。git merge执行合并。合并有两种结果。如果主分支在你创建功能分支之后没有产生新提交Git 会执行 fast-forward 合并把 main 直接快进到功能分支的最新节点历史是一条直线。如果主分支有过新提交Git 会执行三路合并生成一个额外的 merge commit把两条分支的改动汇合成一个新节点。fast-forward 看起来很干净但有个问题它不保留「这是一个功能合并」的边界历史里看不到哪些提交属于同一功能的组装。团队协作时很多人强制使用git merge --no-ff效果是即使可以快进也额外生成一个 merge commit把功能提交打包成一个整体。这个习惯对回溯历史很有价值。--no-ff不是必须的个人项目里 fast-forward 完全够用。但如果你在带团队建议统一开启并在仓库设置里配置主分支保护禁止直接 push强制走 PR 合并。这是让协作不翻车的基础设施。4.3 冲突处理看懂冲突标记和正确的解决顺序合并时最让人紧张的就是冲突提示。当两条分支改动了同一个文件的同一段代码Git 无法自动决定保留谁只能把问题抛给你。冲突信息会出现在git status里文件列表中显示both modified。打开冲突文件你会看到类似这样的标记 HEAD 当前分支的代码 被合并分支的代码 feat/login-pageHEAD到之间是你当前所在分支的版本到之间是正在被合入分支的版本。你需要做的决定是保留哪一边还是两边都要还是手动组合成新代码。编辑完成后删除所有、、标记这是新手最容易遗漏的一步——内容选好了但标记没删干净Git 依然认为冲突未解决。处理完成后分两步收尾git add conflicted_file.txt git commit第一个命令把解决后的文件加入暂存区告诉 Git 冲突已处理第二个命令生成 merge commit。如果你用的是较新版本的 Git也可以在确认所有冲突文件都git add后执行git merge --continue效果相同但语义更明确。冲突解决过程中有两条铁律第一不要为了解决冲突而随意删除对方分支的改动除非你确定这段代码已经不需要第二解决完本地验证能运行再 push不要带着半吊子冲突结果推到远程否则队友一拉代码就是一片红色错误。5. 避坑手记GitHub 初学者踩过的五个具体坑5.1 把密钥文件提交进了仓库现象项目上线前发现.env文件、数据库密码甚至id_rsa私钥在 Git 历史里躺着而且已经推送到了远程仓库。原因.gitignore没生效或者你用的是git add .一次性把所有文件都纳入了暂存区包括本不该提交的敏感文件。解决如果还没推到远程直接移出暂存区并提交一次删除即可git rm --cached .env echo .env .gitignore git add .gitignore git commit -m chore: remove env file from tracking git push--cached参数只把文件从 Git 跟踪中移除保留本地文件。但如果密钥已经被推上去过光是删除最新节点不够历史里依然能翻出来。个人项目最省事的后悔药是删掉仓库重建一个——反正也没有协作历史要保留。团队项目则需要用git filter-repo重写历史并通知所有成员强制同步新历史这个操作牵一发动全身建议先在本地备份测试。5.2 大文件直接入库导致仓库体积失控现象push 时报错pack exceeds limit或者仓库体积莫名膨胀到几百 MB克隆一次要等很久。原因把node_modules、dist构建产物、视频文件塞进了 Git。GitHub 单文件上限是 100 MB超过直接拒收没超过但体积很大的文件也会让仓库历史越来越臃肿。解决第一步是建立.gitignore把依赖目录和构建产物排除在版本控制外。第二步如果历史里已经有大文件可以考虑用git filter-repo清理git filter-repo --path node_modules --invert-paths这条命令把node_modules从全部历史中移除。注意这会重写所有 commit 的 hash任何协作者都要重新克隆不能直接 pull。仓库里有大文件时要改策略用 Git LFS 管理二进制文件或者干脆把构建产物放到独立的制品服务器。5.3 pull 把本地未提交改动直接覆盖现象本地改了几个文件还没 commit执行git pull后改动不见了或者提示无法拉取。原因git pull 默认会尝试合并远程改动如果本地有未提交的修改且与远程改动位置重叠Git 会拒绝操作。但如果你在界面工具里强制选择了「覆盖本地」未提交的改动就真的没了。解决养成 pull 前先看git status的习惯。有未提交改动时先git stash把改动暂存起来pull 完成后再git stash pop恢复。或者直接git pull --rebase它会先把远程提交放到本地提交之下再把本地改动叠加回去历史更干净。我用--rebase纯属个人习惯但建议你确认自己理解 rebase 的含义再用毕竟它同样会重写提交历史。5.4 访问 GitHub 频繁失败第一反应不要换镜像现象git clone下载到一半超时push 连接经常断开但浏览器访问 github.com 偶尔能打开。原因GitHub 的 CDN 节点在国内访问存在不稳定因素这属于网络环境问题不是你的代码或 Git 配置有问题。解决排查顺序是这样的。先把 SSH 端口从默认的 22 改成 443很多网络环境会特殊对待 443 端口vim ~/.ssh/config写入以下内容Host github.com Hostname ssh.github.com Port 443然后测试ssh -T gitgithub.com。如果还是慢可以用浅克隆减少传输量git clone --depth 1 gitgithub.com:yourname/yourrepo.git--depth 1只拉取最新一条提交记录不下载完整历史体积大幅缩小。至于网上流传的各种镜像站我的建议是不要太依赖镜像同步有延迟你 clone 到的可能不是最新代码而且你无法确认镜像站是否会在代码里做手脚。与其为了下载快一点承担供应链风险不如直接用 SSH 方式慢就慢点拉。5.5 一个仓库装下所有东西没有组织边界现象一个 repo 里既有前端代码又有后端代码还有 iOS 工程和一堆无法归类的散文件仓库名也叫得含糊比如test、myproject。原因建仓库时没有想清楚边界所有代码一锅端。拖拽上传文件夹的网页操作也加剧了这种混乱——文件夹嵌套和链接文件处理在网页端很容易出错。解决按职责拆仓库前端一个、后端一个、文档按需单独建仓库或放到独立目录。如果你需要 monorepo至少要在仓库里用packages/这类目录隔离模块边界。每个仓库的 README 写清楚它的用途和进入路径。这样设计后权限分配、PR 审查、版本发布都能按模块操作不会一个仓库牵动所有项目。6. 把教程用到实处PR 工作流与开源贡献的最后一公里PDF 里最后两块内容——发起请求和探索贡献——对应到实际操作里就是 Pull Request PR和 fork。PR 不只在给开源项目提代码时用团队内部协作同样适用。标准流程是fork 或新建分支 → 克隆到本地 → 创建功能分支 → 提交并推送 → 在 GitHub 页面选择 Compare pull request → 填写 PR 描述 →等待审查和讨论 → 合并并关闭 PR。参与开源项目时PR 描述里要把这个改动解决什么问题、改动了哪些文件、测试过什么场景说清楚维护者每天收到大量 PR描述潦草的直接被忽略。如果你想了解 GitHub 上某个项目的运行方式和开发节奏正确顺序是先 fork 到自己的账号clone 下来读 README安装依赖跑通测试再探索代码结构最后再考虑提 PR。这个过程比直接在仓库页面点来点去有效得多。日常开发提效我更推荐用 GitHub CLI 替代部分网页操作。比如创建一个 PRgh pr create --base main --head feat/login-page --title feat: add login page --body oauth integration with github--base指定合并目标分支--head指定来源分支--title和--body分别是标题和描述。推送完分支后敲这行命令PR 就创建好了不需要在网页上翻找入口。我过去赶工最凶的时候习惯把代码直接推到 main 分支觉得开分支发 PR 是走流程浪费时间。直到有次推错了文件影响了另一个正在联调的后端同事的接口数据我才意识到主分支被随意改动有多危险。从那以后我每做一个改动都强制走一遍「分支 PR 审查」的闭环哪怕是只改一个错别字也要开分支——代价只是多敲两条命令但换来的是一次完全可追溯的变更记录。GitHub 这套流程的设计初衷就是这个教程 PDF 给了你路径图的骨架真正把它变成肌肉记忆还要靠日常每一次提交里对自己多一点要求。希望帮到你。本文还有配套的精品资源点击获取