简介这份文档面向刚接触版本控制或希望系统梳理Git与GitHub用法的开发者从零基础入门到进阶协作均有覆盖适合学生、职场程序员以及想通过开源项目积累经验的技术爱好者。资源包共1个docx文件约17KB内容以图文步骤与命令示例为主轻量易读便于随时查阅。文档围绕账户注册、仓库创建、本地克隆、代码提交与推送、分支创建与合并等核心操作展开并延伸至Pull Request、Issue等协作机制帮助读者理解团队开发流程与代码质量管理思路。已有1332人学习说明其在入门与进阶过渡阶段具有较高参考价值。读者可借此掌握Git基本命令与GitHub进阶特性优化本地编程环境加速代码迭代并逐步提升开源贡献与职业社交能力。1. GitHub 使用教程从 clone 第一个仓库到把 CI 跑绿中间隔着多少坑很多人第一次打开 GitHub是被一个具体需求推着走的想下载某个开源项目的 release 包结果点进仓库页面一脸懵不知道 Code 按钮在哪、Release 藏在右侧栏、clone 下来又发现没有构建脚本。GitHub 使用教程这类内容网上一抓一大把但真正能让人从新手入门走到高级功能全掌握的往往不是那些罗列按钮的图文而是一条能跑通的路径账号怎么配、仓库怎么建、本地怎么连、分支怎么合、Actions 怎么跑、出问题去哪看日志。这篇笔记面向两类人一类是刚接触 GitHub、连 SSH key 和 HTTPS 都分不清的新手另一类是已经会 push/pull但一遇到冲突、CI 失败、大文件推送就翻车的熟手。我会按「账号与本地环境 → 仓库与分支 → 协作与 PR → Actions 自动化 → 避坑排查 → 进阶技巧」的顺序讲每一步都给出可复制的命令和参数说明。GitHub 本身不复杂复杂的是它把 Git、CI、包管理、权限模型揉在了一起任何一个环节配错都会让你卡半天。下面从最基础的环境配置开始。2. 账号、SSH 与本地环境把第一次 push 跑通2.1 为什么优先用 SSH 而不是 HTTPS新手最常见的做法是复制 HTTPS 地址直接 clone然后每次 push 都弹账号密码。GitHub 早在 2021 年就取消了密码认证现在 HTTPS 推送必须用 Personal Access TokenPAT。PAT 的坑在于它有过期时间、有细粒度权限、一旦泄露要立刻吊销而且每次换机器都要重新配。相比之下SSH key 一次生成、长期有效配置好之后 push/pull 全程无感。我一般会建议个人开发机一律用 SSHCI 环境或临时容器再用 token。SSH 的另一个好处是你可以用~/.ssh/config给不同账号配不同 key这对同时维护公司仓库和个人仓库的人很实用。生成 key 的命令如下# 生成 ed25519 密钥比 RSA 更短更安全 ssh-keygen -t ed25519 -C your_emailexample.com # 一路回车默认存到 ~/.ssh/id_ed25519 # 如果已有 key指定新文件名避免覆盖 ssh-keygen -t ed25519 -C workexample.com -f ~/.ssh/id_ed25519_work参数说明-t ed25519指定算法-C是注释通常写邮箱方便识别。生成后会得到两个文件id_ed25519是私钥绝对不能外传id_ed25519.pub是公钥要粘贴到 GitHub。接下来把公钥加到 GitHub进入 Settings → SSH and GPG keys → New SSH key把.pub文件内容整段贴进去。然后验证# 测试连接-T 表示不分配 shell ssh -T gitgithub.com # 成功会返回Hi username! Youve successfully authenticated...如果卡住或报Permission denied (publickey)先确认 ssh-agent 是否加载了 keyeval $(ssh-agent -s) ssh-add ~/.ssh/id_ed255192.2 全局配置与换行符陷阱Git 装好后第一件事是配用户名和邮箱否则 commit 记录里会显示成随机主机名git config --global user.name Your Name git config --global user.email your_emailexample.com # 查看当前配置 git config --list这里有个血泪经验Windows 和 Linux/Mac 的换行符不同Windows 是 CRLFUnix 是 LF。如果不配core.autocrlf跨平台协作时会出现「整个文件都变了」的假 diff。常见做法是# Windows 上检出时转 CRLF提交时转 LF git config --global core.autocrlf true # Mac/Linux 上保持 LF提交时不转换 git config --global core.autocrlf input更稳妥的方案是在仓库根目录放一个.gitattributes文件强制指定文本文件的换行符这样不依赖每个人的本地配置# .gitattributes * textauto *.sh text eollf *.bat text eolcrlf* textauto让 Git 自动判断文本文件*.sh text eollf保证 shell 脚本在 Windows 上检出也是 LF避免「脚本在 Windows 上跑不了」的问题。2.3 克隆仓库的三种方式与选择克隆有三种常见写法用途不同# 完整克隆带全部历史适合日常开发 git clone gitgithub.com:user/repo.git # 浅克隆只取最近 1 次提交适合只看代码或 CI 拉取 git clone --depth 1 gitgithub.com:user/repo.git # 只克隆某个分支减少体积 git clone --branch main --single-branch gitgithub.com:user/repo.git--depth 1在 CI 里很常用能把克隆时间从几十秒降到几秒代价是拿不到完整历史git log和git blame会受限。如果你要基于历史做分析就别用浅克隆。克隆下来后先看仓库结构再动手ls -la cat README.md # 看远程地址确认用的是 SSH 还是 HTTPS git remote -v如果发现 remote 是 HTTPS可以改成 SSH避免每次输 tokengit remote set-url origin gitgithub.com:user/repo.git3. 分支、提交与 PR把协作流程走顺3.1 分支模型别一上来就搞 Git Flow新手入门阶段最容易犯的错是照搬网上那套 Git Flowmain、develop、feature、release、hotfix 五套分支。对个人项目或小团队来说这套模型维护成本极高合并冲突会多到让你怀疑人生。我一般推荐简化版main 保持可发布feature 分支做开发PR 合并前跑 CI。# 从 main 拉新分支命名带类型和简短描述 git checkout -b feat/login-validation # 或者用 switch语义更清晰 git switch -c fix/header-overflow分支命名建议用feat/、fix/、chore/前缀方便在 PR 列表里筛选。分支名不要用中文和空格否则在某些 CI 环境里会出问题。3.2 提交信息与原子提交提交信息不是写给自己看的是写给未来的你和 code review 的人看的。常见规范是 Conventional Commitsgit add src/login.js git commit -m feat(login): add email format validation git commit -m fix(api): handle 401 response in token refresh格式是type(scope): description。type 常用 feat、fix、docs、style、refactor、test、chore。scope 是模块名。这样写的好处是后续可以用工具自动生成 changelog也方便在 GitHub 上按类型过滤提交。原子提交的意思是一个提交只做一件事。不要「改了登录逻辑 顺手格式化了整个文件 升级了依赖」塞进一个 commit。一旦出问题回滚会非常痛苦。我习惯在 commit 前用git diff --staged再看一遍暂存区确认没有误加的文件。# 查看暂存区和工作区的差异 git diff --staged # 交互式暂存可以只提交文件的一部分改动 git add -pgit add -p是熟手必备技能它会把每个改动块逐个问你是否暂存适合把一个大改动拆成多个原子提交。3.3 PR 的创建、Review 与合并推分支到远程后GitHub 会提示你创建 Pull Requestgit push -u origin feat/login-validation-u把本地分支和远程分支关联之后直接git push就行。PR 描述里建议写清楚三件事改了什么、为什么改、怎么验证。模板可以放在.github/pull_request_template.md团队统一。Review 阶段常见的操作# 拉取远程分支到本地方便在本地跑测试 git fetch origin git checkout -b review-branch origin/feat/login-validation # 或者直接在原分支上拉最新 git pull --rebase origin maingit pull --rebase会把你的提交挪到 main 最新提交之后保持线性历史。如果团队用 merge commit就别用 rebase否则历史会乱。这个选择要在团队里统一不能各写各的。合并方式有三种Merge commit、Squash and merge、Rebase and merge。Squash 会把 PR 里所有提交压成一个适合提交历史很乱的 PRRebase 保持线性但不生成 merge commitMerge commit 保留完整分支结构。我一般对 feature 分支用 Squash对长期分支用 Merge。3.4 冲突解决先看清再动手冲突是新手最怕的环节其实只要理解「冲突是 Git 不知道你要保留哪一版」就不难。冲突文件里会出现 HEAD 当前分支的代码 要合并进来的代码 feat/other解决步骤# 1. 先看哪些文件冲突 git status # 2. 打开冲突文件手动编辑删掉标记行保留正确内容 # 3. 标记为已解决 git add conflicted-file.js # 4. 继续合并或 rebase git rebase --continue # 如果想放弃这次 rebase git rebase --abort血泪经验解决冲突前先git stash或提交当前工作否则一旦 abort 可能丢改动。另外冲突解决后一定要跑一遍测试因为手动合并很容易漏掉逻辑。4. GitHub Actions把 CI 跑绿的最小配置4.1 一个能跑通的最小 workflowGitHub Actions 的配置文件放在.github/workflows/下用 YAML 写。下面是一个 Node.js 项目的最小 CIname: CI on: push: branches: [main] pull_request: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm test逐段说明on定义触发条件push 到 main 或对 main 发 PR 时触发。runs-on指定运行环境ubuntu-latest是最常用的。actions/checkout把代码拉到 runner 上setup-node装 Node 并缓存 npm 依赖npm ci按 lockfile 精确安装比npm install更适合 CI。4.2 缓存、矩阵与密钥管理缓存能显著缩短 CI 时间。setup-node的cache: npm已经帮你缓存了~/.npm但node_modules本身不缓存。如果项目依赖多可以手动缓存- uses: actions/cachev4 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles(**/package-lock.json) }}key里用 lockfile 的哈希依赖一变缓存就失效避免用到旧依赖。矩阵构建适合多版本测试strategy: matrix: node: [18, 20, 22]这样会并行跑三个 job任何一个失败整个 workflow 就红。密钥管理用 GitHub SecretsSettings → Secrets and variables → Actions → New repository secret。在 workflow 里通过${{ secrets.MY_TOKEN }}引用。注意Secrets 不会自动传给 PR 来自 fork 的 workflow这是安全设计避免恶意 PR 偷密钥。如果确实需要要用pull_request_target但这有安全风险必须谨慎。4.3 看日志与重跑CI 失败后点进 Actions 页面展开失败的 step 看日志。常见失败原因依赖装不上网络或版本问题、测试超时、环境变量缺失、权限不足。日志里搜Error和exit code最快定位。重跑单个 job右上角 Re-run jobs → Re-run failed jobs。如果怀疑是缓存问题勾选「Re-run all jobs」并清缓存。5. 避坑与排查那些让新手卡半天的常见问题5.1 推送被拒rejected non-fast-forward现象git push报! [rejected] main - main (non-fast-forward)。原因远程有你本地没有的提交通常是别人先推了或者你在网页上改过文件。解决先拉再推。如果本地没有未提交改动用git pull --rebase origin main把远程提交挪到前面再 push。如果有冲突按第 3.4 节解决。不要直接git push -f除非你确定要覆盖远程历史这在协作分支上是禁忌。5.2 大文件推送失败GH001 或 pack 超限现象push 时报remote: error: GH001: Large files detected或pack exceeds maximum allowed size。原因GitHub 单文件限制 100MB仓库推荐不超过 1GB。误提交了模型文件、数据集、视频。解决如果还没 push用git reset HEAD~1撤回提交把大文件加进.gitignore。如果已经 push需要用git filter-repo重写历史# 安装 git-filter-repo 后 git filter-repo --path large-file.bin --invert-paths git push --force重写历史会影响所有协作者必须提前通知。更稳妥的做法是用 Git LFS 管理大文件git lfs install git lfs track *.psd git add .gitattributes5.3 克隆慢或打不开现象git clone卡在Receiving objects或者网页加载不出来。原因网络到 GitHub 的链路不稳定DNS 解析慢或者走了不合适的出口。解决常见做法是配 hosts 或换镜像源。但要注意镜像站有同步延迟可能拿到旧代码。如果只是下载 release 包可以用curl -L直接下curl -L -o release.zip https://github.com/user/repo/releases/download/v1.0.0/release.zip-L跟随重定向-o指定输出文件名。如果 clone 慢可以先用--depth 1减少数据量或者用git config --global http.postBuffer 524288000调大缓冲区对某些网络环境有效但不是万能药。5.4 CI 在 fork 的 PR 上拿不到 Secrets现象PR 来自 fork 时workflow 里${{ secrets.X }}为空相关 step 失败。原因GitHub 默认不把 Secrets 传给 fork 的 PR防止恶意代码偷密钥。解决如果确实需要在 fork PR 上跑需要密钥的测试用pull_request_target触发但要把 checkout 指向 PR 的 merge commit 而不是 head并且不要在 workflow 里执行不可信代码。更安全的做法是把需要密钥的测试拆到单独的 workflow只在 push 到主仓库时跑。5.5 误删分支或提交后的恢复现象删了分支或git reset --hard后想找回。原因Git 的对象还在只是没有引用指向它。解决用git reflog找到操作记录git reflog # 找到目标 commit 的 hash git checkout -b recovered-branch hashreflog默认保留 90 天是最后的后悔药。但如果是git push --force覆盖了远程且本地也没有那就真找不回来了。6. 进阶技巧把 GitHub 用成工作台而不只是代码托管走到这一步你已经能完成日常的 clone、分支、PR、CI。接下来这些技巧能让 GitHub 从「代码托管」变成真正的工作台。第一个是 Issue 模板和自动标签。在.github/ISSUE_TEMPLATE/下放bug_report.md和feature_request.md用户提 issue 时会自动套模板减少无效沟通。配合labeler.yml可以按文件路径自动打标签比如改了docs/就加documentation标签。第二个是 Release 自动化。用softprops/action-gh-release在打 tag 时自动生成 release notes- uses: softprops/action-gh-releasev2 with: generate_release_notes: truegenerate_release_notes会根据 PR 和 commit 自动分类省去手写 changelog。第三个是 CodeQL 安全扫描。在 Security 标签页开启 CodeQL它会定期扫描代码里的注入、越权等问题。对公开仓库免费私有仓库需要 Advanced Security 许可。第四个是ghCLI。装好之后很多操作不用开浏览器gh pr create --title feat: add login --body 描述 gh pr list gh run list gh run view run-id --loggh run view --log能直接在终端看 CI 日志比网页快。最后一个习惯每次开新项目先建.gitignore、.gitattributes、README.md、.github/workflows/ci.yml这四件套。.gitignore按语言选模板.gitattributes统一换行符README 写清怎么跑CI 保证每次 push 都验证。这四样配好后面 90% 的协作问题都不会发生。我自己踩过最深的坑是早期不写.gitattributes导致团队里 Windows 和 Mac 的换行符来回打架一个文件在 diff 里显示全变了review 根本没法看。后来统一加上.gitattributes才消停。GitHub 的高级功能很多但真正拉开效率差距的往往是这些最基础的配置有没有做对。希望帮到你。本文还有配套的精品资源点击获取