简介这份文档面向Git与GitHub的初学者及有一定经验的开发者系统梳理从账号注册、仓库创建到分支管理、代码协作的完整知识链路帮助读者解决版本控制入门难、团队协作流程不清晰等问题。资源包内含1个docx文件压缩后约17KB以图文教程形式呈现便于随时查阅与对照练习。内容覆盖注册账号、创建仓库、克隆到本地、提交推送代码、分支创建与合并等基础操作并延伸至Pull Request、Issue等协作机制兼顾日常开发与开源贡献场景。已有1332人学习适合希望快速掌握Git命令与GitHub进阶特性、优化编程环境并加速代码迭代周期的技术爱好者也可作为参与开源项目积累经验的参考材料。1. 从 clone 到 PR一套能跑通的 GitHub 实战路径很多人第一次打开 GitHub 官网面对满屏英文和陌生按钮第一反应是关掉页面。但如果你正在做开发、写脚本、搞自动化GitHub 几乎是绕不开的一站。它不只是一个“代码托管网站”而是一整套围绕 Git 版本控制构建的协作基础设施——你可以把它理解成一个带版本历史、分支管理、代码审查和自动化流水线的云端工作台。新手入门最怕的不是命令多而是不知道每条命令在什么场景下用高级功能最容易被神化的也不是什么黑科技而是 Pull Request、Actions、Projects 这些真正能省时间的模块。这篇内容按“能上手、能协作、能排错”的路径走一遍适合刚接触 Git 的开发者、需要团队协作的工程师以及想把项目管起来但不想被工具绑架的独立开发者。2. Git 与 GitHub 的分工先把本地仓库跑通再谈云端2.1 为什么先装 Git 再注册 GitHubGit 是本地版本控制工具GitHub 是托管 Git 仓库的远程平台。两者关系类似“相机”和“云相册”没有相机云相册里什么也存不了。很多新手直接去 GitHub 网页上点“Create repository”然后发现本地没有 Git连 clone 都执行不了。常见做法是先在本地装好 Git配置用户名和邮箱再注册 GitHub 账号这样从第一天起本地提交记录就能正确关联到你的账号。Windows 用户去 Git 官网下载安装包安装时注意勾选“Git Bash Here”和“Add to PATH”macOS 用户直接brew install git或安装 Xcode Command Line ToolsLinux 用户用包管理器安装即可。装完后打开终端验证git --version # 输出类似 git version 2.43.0 即安装成功 git config --global user.name 你的名字 git config --global user.email 你的邮箱 # 这两条配置会写入 ~/.gitconfig后续所有提交都会带上这个身份user.name和user.email建议与 GitHub 账号保持一致否则提交记录在 GitHub 上不会显示你的头像和主页链接。--global表示全局生效如果某个项目需要用不同身份可以在项目目录下不加--global重新配置。2.2 本地仓库的四个核心操作本地仓库的日常操作可以归纳为四个动作改文件、暂存、提交、看历史。下面用一个最小示例走一遍mkdir my-project cd my-project git init # 初始化本地仓库生成隐藏的 .git 目录 echo # My Project README.md git status # 查看当前状态会显示 README.md 是 untracked git add README.md # 把文件加入暂存区准备提交 git commit -m docs: 初始化 README # 提交到本地仓库-m 后面是提交信息 git log --oneline # 查看提交历史--oneline 让每条记录只显示一行git add和git commit是 Git 最核心的两步add 决定“这次提交包含哪些改动”commit 决定“这些改动作为一个快照存下来”。新手最容易犯的错是改了一堆文件后直接git commit -am结果把不该提交的临时文件也带进去了。稳妥做法是每次提交前先git status看一眼确认暂存区里只有你真正想提交的内容。提示提交信息建议用type: 描述的格式比如feat: 增加登录接口、fix: 修复分页越界后续排查问题时能快速定位。3. 远程协作把本地提交推到 GitHub 并参与开源项目3.1 关联远程仓库与推送分支本地仓库建好后需要在 GitHub 上创建一个空仓库然后把两者关联起来。GitHub 创建仓库时不要勾选“Initialize this repository with a README”否则远程会有一个本地没有的提交第一次 push 会报冲突。git remote add origin https://github.com/你的用户名/my-project.git # origin 是远程仓库的默认别名可以改成别的名字 git branch -M main # 把当前分支重命名为 main与 GitHub 默认分支保持一致 git push -u origin main # -u 表示把本地 main 和远程 main 关联后续直接 git push 即可git remote add只是建立关联不会自动同步任何内容。git push -u origin main第一次推送时会要求输入 GitHub 用户名和密码但 GitHub 已经不支持密码推送需要用 Personal Access Token 代替。在 GitHub 的 Settings → Developer settings → Personal access tokens 里生成一个 token勾选repo权限复制后当作密码粘贴即可。3.2 分支、合并与 Pull Request 的完整流程团队协作不会所有人都在 main 分支上直接改。常见做法是每个功能开一个分支改完推上去通过 Pull Request 合并。下面模拟一个完整流程git checkout -b feature/add-login # 创建并切换到 feature/add-login 分支 # 修改代码后 git add . git commit -m feat: 增加登录接口 git push origin feature/add-login # 把功能分支推到远程 # 然后在 GitHub 网页上点击 Compare pull request # 填写标题和描述指定 reviewer提交 PRPR 提交后GitHub 会自动对比源分支和目标分支的差异。如果目标分支在你开发期间有了新提交PR 页面会提示“This branch has conflicts that must be resolved”。解决冲突的常见做法是本地切回 main拉取最新代码再合并到功能分支git checkout main git pull origin main git checkout feature/add-login git merge main # 如果有冲突Git 会在文件里标记 # 手动编辑解决后 git add . git commit -m chore: 解决与 main 的冲突 git push origin feature/add-login合并完成后PR 页面上的冲突提示会消失reviewer 可以继续审查。审查通过后点击“Merge pull request”功能分支的代码就进入 main 了。合并后可以删除远程功能分支保持仓库整洁。注意git pull默认是 fetch merge如果本地有未提交的改动pull 可能会失败。稳妥做法是 pull 之前先git stash暂存pull 完再git stash pop。4. 避坑与排查GitHub 使用中最容易翻车的五个场景4.1 推送被拒remote contains work that you do not have现象执行git push时报错! [rejected] main - main (fetch first)提示远程有本地没有的提交。原因远程仓库在你上次 pull 之后有了新提交通常是别人推了代码或者你在 GitHub 网页上直接改了文件。解决先git pull origin main把远程改动拉下来合并再git push。如果确定远程改动不需要保留可以用git push --force但强制推送会覆盖远程历史团队协作中慎用。4.2 提交了大文件导致仓库臃肿现象不小心把几百 MB 的数据集或编译产物提交了之后每次 clone 都很慢仓库体积降不下来。原因Git 会保留所有历史提交中的文件即使后来删除了历史记录里依然存在。解决如果还没推送用git reset HEAD~1撤销提交把大文件加入.gitignore后重新提交。如果已经推送需要用git filter-repo或 BFG Repo-Cleaner 清理历史然后强制推送。预防措施是在项目根目录建.gitignore把node_modules/、dist/、*.log、*.zip等写进去。4.3 换行符警告LF will be replaced by CRLF现象Windows 上git add时提示warning: LF will be replaced by CRLF in xxx。原因Windows 和 Unix 的换行符不同Git 默认会自动转换导致警告。解决统一换行符配置。在 Windows 上执行git config --global core.autocrlf true在 macOS/Linux 上执行git config --global core.autocrlf input。如果项目有.gitattributes文件按文件里的规则为准。4.4 SSH 密钥配置后仍然提示权限拒绝现象已经生成了 SSH key 并添加到 GitHub但git clone时仍然提示Permission denied (publickey)。原因可能是 key 没有加到 ssh-agent或者克隆时用的是 HTTPS 地址而不是 SSH 地址。解决先ssh -T gitgithub.com测试连接如果提示Hi xxx! Youve successfully authenticated说明 key 没问题。如果失败执行eval $(ssh-agent -s)启动 agent再ssh-add ~/.ssh/id_rsa添加 key。克隆时确认地址是gitgithub.com:user/repo.git格式。4.5 Pull Request 显示大量无关文件变更现象提交 PR 后Files changed 里出现了很多你没改过的文件。原因通常是从错误的分支切出来或者目标分支选错了。比如你想合并到 main但 PR 的目标分支是 develop。解决在 PR 页面点击“Edit”按钮把 base 分支改成正确的目标分支。如果分支本身切错了需要本地重新从正确的基线创建分支把改动 cherry-pick 过去再重新提交 PR。5. 进阶技巧用 Actions 和 Projects 把重复劳动自动化5.1 GitHub Actions 的最小可用配置Actions 是 GitHub 自带的 CI/CD 工具可以在代码推送、PR 创建等事件触发时自动执行脚本。最常见的用途是自动跑测试、自动构建、自动部署。下面是一个 Node.js 项目的测试工作流# .github/workflows/test.yml name: Run Tests on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 # 检出代码到 runner 环境 - uses: actions/setup-nodev4 with: node-version: 20 # 指定 Node.js 版本 - run: npm ci # 安装依赖ci 比 install 更适合 CI 环境 - run: npm test # 执行测试脚本这个配置放在.github/workflows/目录下推送到 GitHub 后自动生效。on定义触发条件jobs定义执行任务steps是具体步骤。每次 push 或 PR 到 main 分支GitHub 会分配一台 Ubuntu 机器按顺序执行这些步骤。如果测试失败PR 页面会显示红色叉号阻止合并。5.2 Projects 看板与 Issue 模板Projects 是 GitHub 的项目管理模块可以看成轻量级的看板工具。在仓库的 Projects 标签页新建一个 Board添加“Todo / In Progress / Done”三列然后把 Issue 拖进去。Issue 可以关联 PRPR 合并后 Issue 自动关闭。常见做法是给仓库加一个 Issue 模板放在.github/ISSUE_TEMPLATE/bug_report.md内容包含复现步骤、期望行为、实际行为、环境信息。这样别人提 Issue 时会自动带上这些字段省去来回追问的时间。5.3 一个我反复用的验证习惯每次提交 PR 之前我会在本地强制走一遍“三查”git status确认没有多余文件git log --oneline -5确认提交信息清晰git diff main...HEAD --stat确认改动范围符合预期。这个习惯帮我拦下过好几次误提交密钥、误改配置文件的事故。Actions 跑通之后我还会在 PR 描述里贴一条“本地测试通过”的评论方便 reviewer 判断优先级。从那以后我每次开 PR 都强制走一遍这个流程省下来的沟通时间远比配置 Actions 花的时间多。希望帮到你。本文还有配套的精品资源点击获取