尧图网页设计 
1. 先弄明白GitHub和Git再开始动手1.1 一句话讲清Git和GitHub的关系很多新手会把Git和GitHub当成一回事其实它们是两样完全不同的东西。Git是一个在你电脑本地运行的版本管理工具负责记录代码每一次的改动相当于一个细到文件行级别的后悔药系统GitHub则是一个基于Git的云端代码托管平台把你的仓库放到网上方便备份、展示和多人协作。打个比方Git是负责记账的档案管理员GitHub是存放档案的云端档案库管理员把账记好后再把账本同步到云端给别人看。对刚接触GitHub的人来说你需要掌握的核心工作流其实就三条。第一在本地写代码用Git随时记录每次修改第二把本地记录的一个版本推送到GitHub这个动作叫push第三把GitHub上的最新版本拉回本地这个动作叫pull。一旦把这三条线串起来日常开发的基本循环就成立了你就能理解为什么程序员总说代码放在GitHub上而不只是放在自己电脑上。这篇文章会围绕标题里最核心的两件事展开怎么把一个本地项目上传到GitHub以及改完代码之后怎么把修改内容同步上去。我不打算讲太多理论重点放在可直接照抄的操作流程和真实踩过的坑上。已经会pull / push的老手可以跳过前面两章直接从遇到的报错部分开始看后面几章有不少排查经验值得扫一眼。名词作用通俗解释Git本地版本管理工具记录文件每次变化的账本GitHub云端代码托管平台把本地仓库同步到网上的档案库Repository仓库项目存放位置一个项目对应一个仓库Commit提交保存一个版本给当前文件变化拍一张快照Push推送本地到远程把本地快照传到GitHubPull拉取远程到本地把远程更新同步回本地Clone克隆远程到本地完整复制把别人仓库完整下载到本地1.2 动手之前先把三件事准备好注册GitHub账号。打开GitHub官网点击Sign up按流程填邮箱、密码、用户名。用户名不是邮箱前缀而是一个唯一的公开ID它会在仓库地址里出现别人搜索你、查看你提交的代码都靠它所以取一个自己长期用且不容易撞车的名字。注册完会发一封验证邮件到你的邮箱点一下激活链接账号才算正式开通。安装Git。这是很多人忽略的一步。GitHub网页只能让你上传单个文件、查看代码真正的版本管理能力都在本地Git命令里。Windows用户建议直接去Git官网下载安装包一路默认安装即可安装完成后在开始菜单找Git Bash打开后输入git --version能看到版本号就说明装好了。macOS用户如果装了Homebrew一条命令搞定brew install git。Linux用户对应使用apt install git或yum install git。装完同样用版本命令验证。提示Windows安装Git过程中有一个Adjusting your PATH选项默认选Git from the command line and also from 3rd-party software就行这样能在CMD和PowerShell里直接使用git命令。准备一个本地测试项目。不用折腾什么大项目就在桌面上新建一个文件夹命名为my-first-project里面放一个README.md文本文件随便写两行内容。后面所有操作都在这个文件夹里练跑通流程之后再拿自己的真实项目来操作就不慌了。2. 上传首个本地项目从新建仓库到第一次Push2.1 在GitHub上新建一个干净的远程仓库登录GitHub之后页面右上角有一个号点开后选择New repository进入新建仓库页面。这里的配置项我逐个说因为选错会影响后面推送的顺畅度。Repository name是仓库名建议和本地文件夹名一致比如my-first-projectDescription是仓库简介先填不填无所谓Public和Private是可见范围Public代表公开仓库任何人都能看到适合开源项目和作品展示Private是私有仓库只有你主动添加的协作者能看到新手练习阶段强烈建议先用Private避免把还没处理好的配置信息暴露出去。下面有一个选项叫Initialize this repository with a README这里一定不要勾选。因为我们要练习的是从本地把已有项目推上去这条路如果勾选了GitHub会自动生成一次初始提交本地仓库和远程仓库的历史就对不上了等下推送时会多出合并的麻烦。保持仓库完全是空的直接点击Create repository。创建完成后页面会跳转到仓库主页并显示一段初始化指引里面给出了远程仓库地址。地址通常有两种形式https://github.com/你的用户名/my-first-project.git gitgithub.com:你的用户名/my-first-project.git前者是HTTPS协议第一次push会让你输入账号信息简单直接后者是SSH协议配置一次之后免密推送体验更好。第一次上手先使用HTTPS方式跑通了再换成SSH也不迟。2.2 在本地项目文件夹里初始化Git进入项目文件夹打开终端。Windows用户在文件夹地址栏输入cmd回车Mac用户可以直接在访达里打开终端再cd到对应目录最稳妥的方式是在终端中拖动文件夹图标定位路径。cd ~/Desktop/my-first-project git init执行git init后终端会输出Initialized empty Git repository in ...这样一行提示。这条命令会在当前目录生成一个隐藏的.git文件夹里面放着Git所需的全部元数据你的项目从此就是一个合法的Git仓库了。不要手动去改动.git里的内容它不需要你操心。接下来设置Git身份。这里设置的不是GitHub账号而是提交署名每一次commit都会记录这个信息git config --global user.name 你的名字 git config --global user.email 你的邮箱--global意味着这台电脑上所有仓库都会默认采用这个身份很适合个人电脑使用。如果某个项目想用不同的身份可以去掉--global在项目目录里单独设置优先级会高于全局配置。然后用两条命令完成第一次提交git add README.md git commit -m 第一次提交添加README你会发现Git命令总是先add再commit的固定套路。这里add是把文件放入暂存区commit才是真正生成一个版本记录。-m参数是必须的它后面跟的字符串就是本次提交的说明。如果不写-mGit会进入一个系统默认文本编辑器等你输入说明新手在vim界面里往往不知道怎么退出非常影响体验所以请一定记得加-m。执行完commit后用git status看一眼当前状态如果显示nothing to commit, working tree clean说明本地仓库已经记录好当前版本可以推送了。2.3 关联远程仓库完成第一次推送现在把本地仓库和GitHub上的远程仓库连起来。git remote add origin https://github.com/你的用户名/my-first-project.git这里的origin是Git给远程仓库起的默认别名用来代替一长串地址。你可以理解成给朋友手机号存了备注名以后打电话不用拨号喊一声origin就拨出去了。接下来把本地当前分支的名字改成main。这里有个背景GitHub官方现在默认主分支叫main而早期Git初始化时默认分支叫master为了两边的分支名保持一致需要执行一条改名命令git branch -M main然后正式推送git push -u origin main-u的全称是--set-upstream它的作用是让本地main分支和远程main分支建立跟踪关系。有了这个关系以后在这个分支上直接敲git push就能推送不需要再重复写origin main。第一次执行push时终端会弹出一个登录窗口要求输入GitHub的用户名和密码。这里有一个新手必踩的坑密码栏里输入的并不是你登录GitHub的账号密码而是Personal Access Token也就是个人访问令牌。GitHub早已不再接受账号密码形式的git操作认证如果你老老实实输入登录密码一定会得到Authentication failed的报错。具体怎么生成这个Token我在第五章节里详细讲。当你正确输入用户名和Token之后终端会输出一堆打包信息最后出现main - main之类的字样就说明push成功了。回到GitHub仓库页面刷新一下README.md已经躺在文件列表里。这一步是整个GitHub学习曲线里最陡的一关跑通之后一切都会变得顺理成章。3. 修改本地项目后的同步流程add、commit、push三件套3.1 理解工作区、暂存区、版本库的关系项目首次上传到GitHub后你日常面对最多的场景就是改了一个或多个文件想把这些改动同步到GitHub。很多人第一次接触时直接问我怎么更新GitHub上的文件其实底层就是三个命令合起来叫提交三件套git add . git commit -m 更新说明 git push虽然看起来简单但盲目复制命令会让你在出现问题时完全摸不着头脑。这三个命令背后对应着Git的三个核心区域我建议你花五分钟理解一下。第一个是工作区Working Directory也就是你在VS Code、记事本里打开的文件本身你改哪一行代码改动都先发生在这里。第二个是暂存区Staging Area用git add把工作区里想提交的文件放进去相当于去超市购物时推的购物车你先选择把哪些商品放进去最后再结账。第三个是版本库Repository用git commit把暂存区里的内容正式结算成一个版本得到一个不可变的历史快照。拿一个具体例子串一遍。假设你的README.md里本来写着这是一个测试项目你改成这是一个GitHub练习项目保存文件后改动只存在于工作区。如果你直接执行git pushGit会告诉你当前没有可推送的内容因为改动还没被记录。正确的动作是先git add README.md把改动放进暂存区再git commit -m 更新项目介绍生成一个新版本最后git push推送到GitHub。如果改动的文件很多git add .会把工作区里所有被修改、被删除以及新增的文件全部放进暂存区效率确实高副作用是按文件筛选的精细度没了。所以我个人的经验是如果改动只涉及两三个已知文件就精确添加如果确实是一次大型改动、很多文件一起改完再用git add .也不迟。3.2 怎么用git status和git diff确认改动推送之前强烈建议先看一眼当前仓库状态这个操作能避免大量手滑事故git status输出的内容会告诉你三件事当前在哪个分支、哪些文件有改动、这些改动是被暂存还是没有暂存。比如Changes not staged for commit: (use git add file... to update what will be committed) (use git restore file... to discard changes in working directory) modified: README.md看到这一行说明README.md有改动但还没有add。如果想更进一步确认具体改了什么内容执行git diff README.mdgit diff会以增量对比的方式显示每一行的变动-开头的是原来的内容开头的是当前的内容。看一遍diff再提交基本能避免我以为我改的是这个结果提交了另一个的低级错误。3.3 提交信息到底怎么写才不后悔git commit -m 更新这种写法我见过太多了。一天提交五次五次都是更新等过一个月想回滚到某次改动翻提交历史时你会想抽当时的自己。提交信息是写给未来的自己和协作队友看的最基本的要求是说明这次改动做了什么、为什么要做。业界有一个朴素的约定用动词开头常见的有这样几类feat: 新增了用户登录功能fix: 修复登录按钮点击无响应的问题docs: 更新README文档style: 调整代码缩进和格式refactor: 重构用户模块的代码结构不一定非要按Conventional Commits的规范来但我强烈建议至少做到动词 具体对象 问题描述的格式。比如git commit -m fix: 修复首页在移动端样式错乱的问题多看几眼GitHub上知名开源项目的提交记录你会发现大家的写法都高度类似。这个习惯从第一天就培养后面受益无穷。3.4 推送之前先拉取避免冲突的关键习惯如果你的仓库只有一台电脑在用push基本不会出问题。但只要仓库被另一台电脑、另一个协作者或者你自己在GitHub网页端改过文件本地仓库就可能落后于远程仓库。这时候直接pushGit会拒绝推送并提示non-fast-forward之类的错误。正确的习惯是推送之前先同步远程的最新改动。git pull origin maingit pull本质上做了两步先从远程下载最新提交到本地也就是fetch再把下载下来的内容合并到当前分支也就是merge。如果远程有改动而你没先pullpush就会被拒绝pull之后再把本地改动push上去流程就顺了。如果没有冲突pull会自动完成合并你继续push即可。如果远程和本地改动的是同一个文件的同一行Git无法自动判断谁对这时候会出现冲突CONFLICT并在冲突文件里用、、标记出两边的内容。打开文件手动保留需要的部分删掉冲突标记然后重新add、commit、push冲突就解除了。第一次遇到冲突确实会紧张但它本质是在帮你做版本裁决你和我改的是同一个地方到底听谁的你自己看清楚决定。所以我会建议形成这样一个操作顺序改代码之前先pull改完之后commit再push。这样能最大程度减少冲突的发生。4. 上传文件夹、大文件与忽略规则4.1 整个项目文件夹怎么一次传上去如果你之前没有为项目做过Git初始化现在有一个完整的项目文件夹里面有多个子目录、多个文件想一次性上传到GitHub流程跟单文件一致区别只在git add的范围。cd 项目根目录 git init git add . git commit -m 上传整个项目 git remote add origin https://github.com/你的用户名/仓库名.git git branch -M main git push -u origin main执行完这串命令Git会递归扫描整个文件夹把所有文件和文件夹的相对路径一并记录并推送。这里有一个很容易踩的点本地新建的空文件夹通过git add .并不会被上传到GitHub。原因是Git只跟踪文件不跟踪目录它要求目录里至少有一个文件才存在。想让空文件夹出现在远程仓库里通用的土办法是在里面放一个占位文件命名通常叫.gitkeep内容留空纯粹用来占坑。这不是GitHub的限制而是Git本身的设计明白原理之后就不会再困惑。如果你只是临时想传一个文件夹不想初始化整个项目的Git历史GitHub网页端直接支持拖拽上传仓库页面进入目标目录点击Add file下拉菜单里的Upload files然后把整个文件夹拖进浏览器窗口就行。网页端会自动创建文件夹结构。但这个方案有两个明显缺点一是无法保留版本记录二是大文件列表容易卡住。适合传一次就完事的场景正式开发不建议用。4.2 .gitignore把不需要提交的文件挡在门外项目里不是所有文件都应该进Git。最常见的例子是node_modules一个JavaScript项目装完依赖后这个目录体积轻松超过几百MB里面全是可重新生成的第三方代码完全没有入库的必要。如果被误传上去对仓库是灾难性的。解决方式是项目根目录放一个.gitignore文件在里面写明哪些路径、哪些规则需要忽略。一个典型的例子node_modules/ dist/ build/ .env .env.local *.log .DS_Store Thumbs.db规则很直白node_modules/表示忽略这个目录以及目录下所有内容.env表示忽略这个文件*.log表示忽略所有.log后缀文件.DS_Store是macOS系统自动生成的元数据文件应该忽略。把.gitignore写好之后再执行git add .时这些文件会被自动跳过。刚开始拿真实项目上传时建议先写.gitignore再add不要等到git status里出现一大堆没打算传的文件才想起处理。4.3 大文件和二进制资源别硬塞进仓库GitHub对上传文件大小有硬性限制单文件超过50MB会出现警告超过100MB时push会被直接拒绝。如果你的真实项目里有训练好的模型权重、安装包、视频素材这类大文件硬往GitHub塞不仅会失败就算侥幸传上去每次clone也会把仓库拖到非常慢。处理大文件的思路通常有三个。第一小体积素材比如图标、图片直接入库没问题第二大体积程序文件放网盘、对象存储通过URL访问第三如果确实需要版本管理大文件Git LFSLarge File Storage可以帮忙它会把大文件替换成轻量指针文件实际内容存到LFS服务器上。但LFS免费额度大约只有1GB配置也有所门槛小项目直接用网盘方案更省心。push报错的时候通常会看到类似this exceeds GitHubs file size limit of 100 MB的提示。处理顺序是先用git log找到包含大文件的提交再用git rm --cached把它从Git目录中移除然后把它加进.gitignore最后重新commit和push。如果这个文件已经被历史提交记录了多次光删当前版本不够历史里依然有它就需要重写历史。对新手来说与其折腾filter-branch这种高风险操作不如把本地剩余文件整理干净重新建一个远程仓库传一次反而更省时间。5. 初学GitHub最容易踩的坑和排查思路5.1 认证失败现在必须用Token不是登录密码第一次push就遇到认证失败可以说是GitHub新手最普遍的第一课。报错信息一般是这样的fatal: Authentication failed for https://github.com/你的用户名/my-first-project.git原因大概率很简单你在密码栏里输入的是GitHub登录密码。但GitHub从很早开始就不再接受账号密码形式的git操作现在要求使用Personal Access Token也就是个人访问令牌。生成Token的完整路径是GitHub页面右上角点头像 → Settings → 左侧最下方Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)。做一次会看到一堆字段Note给这个Token起个名字比如我的笔记本Expiration有效期设置建议90天以内长令牌政策在收紧短一点的更安全Select scopes权限范围个人项目勾选repo完整仓库读写权限即可不需要额外选择admin之类的高权限。生成之后页面上会出现一串以ghp_开头的字符串请立刻复制保存。这个Token只显示一次关掉页面后就再也看不到了忘记只能重新生成。之后push时提示输入密码粘贴这串Token进去终端里输入内容不会显示任何字符这是正常的不代表死机回车就能完成认证。如果以后每天都要push每次都输入Token确实烦人那就用上一章提到的SSH配置解决。5.2 push被拒绝non-fast-forward该怎么处理! [rejected] main - main (non-fast-forward) error: failed to push some refs to https://github.com/... hint: Updates were rejected because the tip of your current branch is behind its remote counterpart.看到这串报错含义是你本地的版本落后于远程版本Git拒绝用落后的版本覆盖远端。新手第一反应经常是那我强制覆盖吧这里我必须提醒你git push -f这种强制推送能不用就不用尤其是多人协作或公开仓库覆盖意味着别人辛苦推上去的代码会消失。正确的解决顺序git pull origin main git push先拉取远程更新合并到本地再推送。如果拉取过程中报了冲突进入3.3提到的冲突解决流程手动处理后再add、commit、push。还有一个进阶选项是git pull --rebase origin mainrebase会把本地提交垫到远程最新提交之后提交历史更干净但依然可能弹冲突处理方式相同。新手从普通pull开始就够了。5.3 误提交、误删除怎么优雅回滚开发过程中难免手滑把不该提交的文件放进去了或者提交信息写错了。Git给了不少后悔药但要分清场景用错了更麻烦。如果只是想从Git跟踪中移除一个文件但保留本地文件用git rm --cached 文件名比如误把.env提交上去了这条命令能把它移出Git跟踪再配合.gitignore防止之后再被add非常实用。如果想撤销最近一次commit但保留改动内容用git reset --soft HEAD~1HEAD~1指的是上一个版本--soft表示只回退commit记录暂存区和工作区都不动。适合提交信息写错了或者提交完之后发现还忘加一个文件的场景。如果想连暂存区也清空但不想丢弃工作区修改用git reset --mixed HEAD~1这是不带参数的默认行为。如果连工作区改动也想彻底丢弃才用git reset --hard HEAD~1请特别注意--hard会丢弃最后一次提交里的所有文件改动是不可恢复的执行前一定要确认本地内容不需要了。我见过不止一个同事在没备份的情况下敲了--hard然后对着消失的代码怀疑人生。如果已经push到远程了才发现提交有问题更推荐的做法是在GitHub网页端操作Revert进入Commits列表找到问题提交点击Revert按钮GitHub会自动生成一条反向提交既保留历史又撤销改动。这种方式对新手最友好因为不会动你的本地历史。5.4 新手问题速查表错误现象常见原因解决办法Authentication failed用了登录密码而非Token生成PAT作为密码输入non-fast-forward rejected本地版本落后于远程git pull origin main再pushFile size limit 100 MB上传了超过100MB的文件移除大文件改用LFS/网盘文件没有出现在push里.gitignore匹配到了目标检查.gitignore规则并调整空文件夹没上传成功Git不跟踪空目录添加占位文件如.gitkeepLF will be replaced by CRLFWindows换行符处理警告正常提示无需处理Permission denied (publickey)SSH密钥未配置正确检查公钥是否已添加到GitHub忘了当前在哪个分支分支切换后没有查看git branch -v 查看当前分支这张表基本覆盖了头一个月能用到的坑。遇到报错不要慌先把这个报错信息复制到搜索引擎里搜GitHub相关的报错大概率已经有人踩过千百次了。6. 三个提升推送效率的实用技巧6.1 配置SSH告别每次输TokenHTTPS方式第一次用起来方便但天天push的话每次输入用户名和Token真的很烦。SSH方式一次性配置终身免密强烈建议早点换。整个流程四步走。第一步生成SSH密钥对。在终端执行ssh-keygen -t ed25519 -C 你的邮箱一路回车即可如果需要设置密码口令就输入一个。执行完会在~/.ssh目录下生成两个文件id_ed25519是私钥绝不能给别人看id_ed25519.pub是公钥可以放心公开。第二步查看公钥内容并复制。执行cat ~/.ssh/id_ed25519.pub以ssh-ed25519开头的一长串字符串就是公钥把它整段复制下来。第三步在GitHub上添加公钥。进入Settings → SSH and GPG keys → New SSH keyTitle随便填粘贴公钥保存。第四步把远程仓库地址换成SSH形式。在项目目录执行git remote set-url origin gitgithub.com:你的用户名/仓库名.git之后执行git push第一次会提示是否确认连接输入yes回车之后就全程无感推送了。这一步配好之后配合VS Code等编辑器自带的Git功能体验可以直接对标商用工具的丝滑。6.2 写一个一键推送的小脚本个人项目改动频繁每次重复敲add、commit、push确实会让人烦。我给自己写了一个小脚本放在项目根目录一行参数就搞定提交说明#!/bin/bash # 用法: ./push.sh 提交说明 cd $(dirname $0) git pull origin main git add . git commit -m $1 git push保存为push.sh之后执行chmod x push.sh赋予执行权限。以后改完代码只需要./push.sh feat: 新增用户列表接口脚本会自动先pull拉取远程更新再提交和推送。我在脚本里特意把pull放在最前面是为了减少push被拒绝的可能性。个人练手、自用项目用这个没问题但在多人协作的项目里还是建议手动确认git add了哪些文件脚本一键全量提交容易把临时文件、调试代码一起推上去得不偿失。6.3 图形化工具的选择建议如果命令行一开始让你觉得门槛偏高完全可以用图形化工具过渡。GitHub官方推出的GitHub Desktop是门槛最低的选择界面简洁Commit、Push、Pull都对应着明确的大按钮文件变更列表也很直观适合第一次建立提交、推送、拉取的肌肉记忆。VS Code内嵌的源代码管理面板也非常实用左侧可以看到每个文件的修改状态、diff对比提交和推送都在同一个面板里几乎所有用VS Code写代码的人都会顺手用它处理Git操作。SourceTree这类老牌工具功能更强分支图可视化更清晰但界面信息密度较高新手一上来容易被绕晕。我的建议是前期用GUI工具能让你快速跑通流程但git status、git log、git diff这几个查询命令还是值得花点时间学会。排查问题、写脚本、在服务器上操作仓库时命令行比任何GUI都直接。最终你会发现它通用、快速、不受图形环境限制这也是很多老手最终还是回到终端的原因。最后分享一个小习惯每开始一个新项目第一时间创建一个.gitignore把日常依赖目录、构建产物、环境配置全部排除掉不要等传了一半才想起处理。还有尽量保持一次提交只做一件事提交信息里说清楚做了什么、为什么做。我见过太多人因为提交信息全是update而无法定位历史版本最后只能逐条翻diff硬查。GitHub的学习曲线说陡也陡说平也平跑通你的第一次push后面就顺了。 GitHub入门实战：从本地项目上传到日常同步的完整指南
1. 先弄明白GitHub和Git再开始动手1.1 一句话讲清Git和GitHub的关系很多新手会把Git和GitHub当成一回事其实它们是两样完全不同的东西。Git是一个在你电脑本地运行的版本管理工具负责记录代码每一次的改动相当于一个细到文件行级别的后悔药系统GitHub则是一个基于Git的云端代码托管平台把你的仓库放到网上方便备份、展示和多人协作。打个比方Git是负责记账的档案管理员GitHub是存放档案的云端档案库管理员把账记好后再把账本同步到云端给别人看。对刚接触GitHub的人来说你需要掌握的核心工作流其实就三条。第一在本地写代码用Git随时记录每次修改第二把本地记录的一个版本推送到GitHub这个动作叫push第三把GitHub上的最新版本拉回本地这个动作叫pull。一旦把这三条线串起来日常开发的基本循环就成立了你就能理解为什么程序员总说代码放在GitHub上而不只是放在自己电脑上。这篇文章会围绕标题里最核心的两件事展开怎么把一个本地项目上传到GitHub以及改完代码之后怎么把修改内容同步上去。我不打算讲太多理论重点放在可直接照抄的操作流程和真实踩过的坑上。已经会pull / push的老手可以跳过前面两章直接从遇到的报错部分开始看后面几章有不少排查经验值得扫一眼。名词作用通俗解释Git本地版本管理工具记录文件每次变化的账本GitHub云端代码托管平台把本地仓库同步到网上的档案库Repository仓库项目存放位置一个项目对应一个仓库Commit提交保存一个版本给当前文件变化拍一张快照Push推送本地到远程把本地快照传到GitHubPull拉取远程到本地把远程更新同步回本地Clone克隆远程到本地完整复制把别人仓库完整下载到本地1.2 动手之前先把三件事准备好注册GitHub账号。打开GitHub官网点击Sign up按流程填邮箱、密码、用户名。用户名不是邮箱前缀而是一个唯一的公开ID它会在仓库地址里出现别人搜索你、查看你提交的代码都靠它所以取一个自己长期用且不容易撞车的名字。注册完会发一封验证邮件到你的邮箱点一下激活链接账号才算正式开通。安装Git。这是很多人忽略的一步。GitHub网页只能让你上传单个文件、查看代码真正的版本管理能力都在本地Git命令里。Windows用户建议直接去Git官网下载安装包一路默认安装即可安装完成后在开始菜单找Git Bash打开后输入git --version能看到版本号就说明装好了。macOS用户如果装了Homebrew一条命令搞定brew install git。Linux用户对应使用apt install git或yum install git。装完同样用版本命令验证。提示Windows安装Git过程中有一个Adjusting your PATH选项默认选Git from the command line and also from 3rd-party software就行这样能在CMD和PowerShell里直接使用git命令。准备一个本地测试项目。不用折腾什么大项目就在桌面上新建一个文件夹命名为my-first-project里面放一个README.md文本文件随便写两行内容。后面所有操作都在这个文件夹里练跑通流程之后再拿自己的真实项目来操作就不慌了。2. 上传首个本地项目从新建仓库到第一次Push2.1 在GitHub上新建一个干净的远程仓库登录GitHub之后页面右上角有一个号点开后选择New repository进入新建仓库页面。这里的配置项我逐个说因为选错会影响后面推送的顺畅度。Repository name是仓库名建议和本地文件夹名一致比如my-first-projectDescription是仓库简介先填不填无所谓Public和Private是可见范围Public代表公开仓库任何人都能看到适合开源项目和作品展示Private是私有仓库只有你主动添加的协作者能看到新手练习阶段强烈建议先用Private避免把还没处理好的配置信息暴露出去。下面有一个选项叫Initialize this repository with a README这里一定不要勾选。因为我们要练习的是从本地把已有项目推上去这条路如果勾选了GitHub会自动生成一次初始提交本地仓库和远程仓库的历史就对不上了等下推送时会多出合并的麻烦。保持仓库完全是空的直接点击Create repository。创建完成后页面会跳转到仓库主页并显示一段初始化指引里面给出了远程仓库地址。地址通常有两种形式https://github.com/你的用户名/my-first-project.git gitgithub.com:你的用户名/my-first-project.git前者是HTTPS协议第一次push会让你输入账号信息简单直接后者是SSH协议配置一次之后免密推送体验更好。第一次上手先使用HTTPS方式跑通了再换成SSH也不迟。2.2 在本地项目文件夹里初始化Git进入项目文件夹打开终端。Windows用户在文件夹地址栏输入cmd回车Mac用户可以直接在访达里打开终端再cd到对应目录最稳妥的方式是在终端中拖动文件夹图标定位路径。cd ~/Desktop/my-first-project git init执行git init后终端会输出Initialized empty Git repository in ...这样一行提示。这条命令会在当前目录生成一个隐藏的.git文件夹里面放着Git所需的全部元数据你的项目从此就是一个合法的Git仓库了。不要手动去改动.git里的内容它不需要你操心。接下来设置Git身份。这里设置的不是GitHub账号而是提交署名每一次commit都会记录这个信息git config --global user.name 你的名字 git config --global user.email 你的邮箱--global意味着这台电脑上所有仓库都会默认采用这个身份很适合个人电脑使用。如果某个项目想用不同的身份可以去掉--global在项目目录里单独设置优先级会高于全局配置。然后用两条命令完成第一次提交git add README.md git commit -m 第一次提交添加README你会发现Git命令总是先add再commit的固定套路。这里add是把文件放入暂存区commit才是真正生成一个版本记录。-m参数是必须的它后面跟的字符串就是本次提交的说明。如果不写-mGit会进入一个系统默认文本编辑器等你输入说明新手在vim界面里往往不知道怎么退出非常影响体验所以请一定记得加-m。执行完commit后用git status看一眼当前状态如果显示nothing to commit, working tree clean说明本地仓库已经记录好当前版本可以推送了。2.3 关联远程仓库完成第一次推送现在把本地仓库和GitHub上的远程仓库连起来。git remote add origin https://github.com/你的用户名/my-first-project.git这里的origin是Git给远程仓库起的默认别名用来代替一长串地址。你可以理解成给朋友手机号存了备注名以后打电话不用拨号喊一声origin就拨出去了。接下来把本地当前分支的名字改成main。这里有个背景GitHub官方现在默认主分支叫main而早期Git初始化时默认分支叫master为了两边的分支名保持一致需要执行一条改名命令git branch -M main然后正式推送git push -u origin main-u的全称是--set-upstream它的作用是让本地main分支和远程main分支建立跟踪关系。有了这个关系以后在这个分支上直接敲git push就能推送不需要再重复写origin main。第一次执行push时终端会弹出一个登录窗口要求输入GitHub的用户名和密码。这里有一个新手必踩的坑密码栏里输入的并不是你登录GitHub的账号密码而是Personal Access Token也就是个人访问令牌。GitHub早已不再接受账号密码形式的git操作认证如果你老老实实输入登录密码一定会得到Authentication failed的报错。具体怎么生成这个Token我在第五章节里详细讲。当你正确输入用户名和Token之后终端会输出一堆打包信息最后出现main - main之类的字样就说明push成功了。回到GitHub仓库页面刷新一下README.md已经躺在文件列表里。这一步是整个GitHub学习曲线里最陡的一关跑通之后一切都会变得顺理成章。3. 修改本地项目后的同步流程add、commit、push三件套3.1 理解工作区、暂存区、版本库的关系项目首次上传到GitHub后你日常面对最多的场景就是改了一个或多个文件想把这些改动同步到GitHub。很多人第一次接触时直接问我怎么更新GitHub上的文件其实底层就是三个命令合起来叫提交三件套git add . git commit -m 更新说明 git push虽然看起来简单但盲目复制命令会让你在出现问题时完全摸不着头脑。这三个命令背后对应着Git的三个核心区域我建议你花五分钟理解一下。第一个是工作区Working Directory也就是你在VS Code、记事本里打开的文件本身你改哪一行代码改动都先发生在这里。第二个是暂存区Staging Area用git add把工作区里想提交的文件放进去相当于去超市购物时推的购物车你先选择把哪些商品放进去最后再结账。第三个是版本库Repository用git commit把暂存区里的内容正式结算成一个版本得到一个不可变的历史快照。拿一个具体例子串一遍。假设你的README.md里本来写着这是一个测试项目你改成这是一个GitHub练习项目保存文件后改动只存在于工作区。如果你直接执行git pushGit会告诉你当前没有可推送的内容因为改动还没被记录。正确的动作是先git add README.md把改动放进暂存区再git commit -m 更新项目介绍生成一个新版本最后git push推送到GitHub。如果改动的文件很多git add .会把工作区里所有被修改、被删除以及新增的文件全部放进暂存区效率确实高副作用是按文件筛选的精细度没了。所以我个人的经验是如果改动只涉及两三个已知文件就精确添加如果确实是一次大型改动、很多文件一起改完再用git add .也不迟。3.2 怎么用git status和git diff确认改动推送之前强烈建议先看一眼当前仓库状态这个操作能避免大量手滑事故git status输出的内容会告诉你三件事当前在哪个分支、哪些文件有改动、这些改动是被暂存还是没有暂存。比如Changes not staged for commit: (use git add file... to update what will be committed) (use git restore file... to discard changes in working directory) modified: README.md看到这一行说明README.md有改动但还没有add。如果想更进一步确认具体改了什么内容执行git diff README.mdgit diff会以增量对比的方式显示每一行的变动-开头的是原来的内容开头的是当前的内容。看一遍diff再提交基本能避免我以为我改的是这个结果提交了另一个的低级错误。3.3 提交信息到底怎么写才不后悔git commit -m 更新这种写法我见过太多了。一天提交五次五次都是更新等过一个月想回滚到某次改动翻提交历史时你会想抽当时的自己。提交信息是写给未来的自己和协作队友看的最基本的要求是说明这次改动做了什么、为什么要做。业界有一个朴素的约定用动词开头常见的有这样几类feat: 新增了用户登录功能fix: 修复登录按钮点击无响应的问题docs: 更新README文档style: 调整代码缩进和格式refactor: 重构用户模块的代码结构不一定非要按Conventional Commits的规范来但我强烈建议至少做到动词 具体对象 问题描述的格式。比如git commit -m fix: 修复首页在移动端样式错乱的问题多看几眼GitHub上知名开源项目的提交记录你会发现大家的写法都高度类似。这个习惯从第一天就培养后面受益无穷。3.4 推送之前先拉取避免冲突的关键习惯如果你的仓库只有一台电脑在用push基本不会出问题。但只要仓库被另一台电脑、另一个协作者或者你自己在GitHub网页端改过文件本地仓库就可能落后于远程仓库。这时候直接pushGit会拒绝推送并提示non-fast-forward之类的错误。正确的习惯是推送之前先同步远程的最新改动。git pull origin maingit pull本质上做了两步先从远程下载最新提交到本地也就是fetch再把下载下来的内容合并到当前分支也就是merge。如果远程有改动而你没先pullpush就会被拒绝pull之后再把本地改动push上去流程就顺了。如果没有冲突pull会自动完成合并你继续push即可。如果远程和本地改动的是同一个文件的同一行Git无法自动判断谁对这时候会出现冲突CONFLICT并在冲突文件里用、、标记出两边的内容。打开文件手动保留需要的部分删掉冲突标记然后重新add、commit、push冲突就解除了。第一次遇到冲突确实会紧张但它本质是在帮你做版本裁决你和我改的是同一个地方到底听谁的你自己看清楚决定。所以我会建议形成这样一个操作顺序改代码之前先pull改完之后commit再push。这样能最大程度减少冲突的发生。4. 上传文件夹、大文件与忽略规则4.1 整个项目文件夹怎么一次传上去如果你之前没有为项目做过Git初始化现在有一个完整的项目文件夹里面有多个子目录、多个文件想一次性上传到GitHub流程跟单文件一致区别只在git add的范围。cd 项目根目录 git init git add . git commit -m 上传整个项目 git remote add origin https://github.com/你的用户名/仓库名.git git branch -M main git push -u origin main执行完这串命令Git会递归扫描整个文件夹把所有文件和文件夹的相对路径一并记录并推送。这里有一个很容易踩的点本地新建的空文件夹通过git add .并不会被上传到GitHub。原因是Git只跟踪文件不跟踪目录它要求目录里至少有一个文件才存在。想让空文件夹出现在远程仓库里通用的土办法是在里面放一个占位文件命名通常叫.gitkeep内容留空纯粹用来占坑。这不是GitHub的限制而是Git本身的设计明白原理之后就不会再困惑。如果你只是临时想传一个文件夹不想初始化整个项目的Git历史GitHub网页端直接支持拖拽上传仓库页面进入目标目录点击Add file下拉菜单里的Upload files然后把整个文件夹拖进浏览器窗口就行。网页端会自动创建文件夹结构。但这个方案有两个明显缺点一是无法保留版本记录二是大文件列表容易卡住。适合传一次就完事的场景正式开发不建议用。4.2 .gitignore把不需要提交的文件挡在门外项目里不是所有文件都应该进Git。最常见的例子是node_modules一个JavaScript项目装完依赖后这个目录体积轻松超过几百MB里面全是可重新生成的第三方代码完全没有入库的必要。如果被误传上去对仓库是灾难性的。解决方式是项目根目录放一个.gitignore文件在里面写明哪些路径、哪些规则需要忽略。一个典型的例子node_modules/ dist/ build/ .env .env.local *.log .DS_Store Thumbs.db规则很直白node_modules/表示忽略这个目录以及目录下所有内容.env表示忽略这个文件*.log表示忽略所有.log后缀文件.DS_Store是macOS系统自动生成的元数据文件应该忽略。把.gitignore写好之后再执行git add .时这些文件会被自动跳过。刚开始拿真实项目上传时建议先写.gitignore再add不要等到git status里出现一大堆没打算传的文件才想起处理。4.3 大文件和二进制资源别硬塞进仓库GitHub对上传文件大小有硬性限制单文件超过50MB会出现警告超过100MB时push会被直接拒绝。如果你的真实项目里有训练好的模型权重、安装包、视频素材这类大文件硬往GitHub塞不仅会失败就算侥幸传上去每次clone也会把仓库拖到非常慢。处理大文件的思路通常有三个。第一小体积素材比如图标、图片直接入库没问题第二大体积程序文件放网盘、对象存储通过URL访问第三如果确实需要版本管理大文件Git LFSLarge File Storage可以帮忙它会把大文件替换成轻量指针文件实际内容存到LFS服务器上。但LFS免费额度大约只有1GB配置也有所门槛小项目直接用网盘方案更省心。push报错的时候通常会看到类似this exceeds GitHubs file size limit of 100 MB的提示。处理顺序是先用git log找到包含大文件的提交再用git rm --cached把它从Git目录中移除然后把它加进.gitignore最后重新commit和push。如果这个文件已经被历史提交记录了多次光删当前版本不够历史里依然有它就需要重写历史。对新手来说与其折腾filter-branch这种高风险操作不如把本地剩余文件整理干净重新建一个远程仓库传一次反而更省时间。5. 初学GitHub最容易踩的坑和排查思路5.1 认证失败现在必须用Token不是登录密码第一次push就遇到认证失败可以说是GitHub新手最普遍的第一课。报错信息一般是这样的fatal: Authentication failed for https://github.com/你的用户名/my-first-project.git原因大概率很简单你在密码栏里输入的是GitHub登录密码。但GitHub从很早开始就不再接受账号密码形式的git操作现在要求使用Personal Access Token也就是个人访问令牌。生成Token的完整路径是GitHub页面右上角点头像 → Settings → 左侧最下方Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)。做一次会看到一堆字段Note给这个Token起个名字比如我的笔记本Expiration有效期设置建议90天以内长令牌政策在收紧短一点的更安全Select scopes权限范围个人项目勾选repo完整仓库读写权限即可不需要额外选择admin之类的高权限。生成之后页面上会出现一串以ghp_开头的字符串请立刻复制保存。这个Token只显示一次关掉页面后就再也看不到了忘记只能重新生成。之后push时提示输入密码粘贴这串Token进去终端里输入内容不会显示任何字符这是正常的不代表死机回车就能完成认证。如果以后每天都要push每次都输入Token确实烦人那就用上一章提到的SSH配置解决。5.2 push被拒绝non-fast-forward该怎么处理! [rejected] main - main (non-fast-forward) error: failed to push some refs to https://github.com/... hint: Updates were rejected because the tip of your current branch is behind its remote counterpart.看到这串报错含义是你本地的版本落后于远程版本Git拒绝用落后的版本覆盖远端。新手第一反应经常是那我强制覆盖吧这里我必须提醒你git push -f这种强制推送能不用就不用尤其是多人协作或公开仓库覆盖意味着别人辛苦推上去的代码会消失。正确的解决顺序git pull origin main git push先拉取远程更新合并到本地再推送。如果拉取过程中报了冲突进入3.3提到的冲突解决流程手动处理后再add、commit、push。还有一个进阶选项是git pull --rebase origin mainrebase会把本地提交垫到远程最新提交之后提交历史更干净但依然可能弹冲突处理方式相同。新手从普通pull开始就够了。5.3 误提交、误删除怎么优雅回滚开发过程中难免手滑把不该提交的文件放进去了或者提交信息写错了。Git给了不少后悔药但要分清场景用错了更麻烦。如果只是想从Git跟踪中移除一个文件但保留本地文件用git rm --cached 文件名比如误把.env提交上去了这条命令能把它移出Git跟踪再配合.gitignore防止之后再被add非常实用。如果想撤销最近一次commit但保留改动内容用git reset --soft HEAD~1HEAD~1指的是上一个版本--soft表示只回退commit记录暂存区和工作区都不动。适合提交信息写错了或者提交完之后发现还忘加一个文件的场景。如果想连暂存区也清空但不想丢弃工作区修改用git reset --mixed HEAD~1这是不带参数的默认行为。如果连工作区改动也想彻底丢弃才用git reset --hard HEAD~1请特别注意--hard会丢弃最后一次提交里的所有文件改动是不可恢复的执行前一定要确认本地内容不需要了。我见过不止一个同事在没备份的情况下敲了--hard然后对着消失的代码怀疑人生。如果已经push到远程了才发现提交有问题更推荐的做法是在GitHub网页端操作Revert进入Commits列表找到问题提交点击Revert按钮GitHub会自动生成一条反向提交既保留历史又撤销改动。这种方式对新手最友好因为不会动你的本地历史。5.4 新手问题速查表错误现象常见原因解决办法Authentication failed用了登录密码而非Token生成PAT作为密码输入non-fast-forward rejected本地版本落后于远程git pull origin main再pushFile size limit 100 MB上传了超过100MB的文件移除大文件改用LFS/网盘文件没有出现在push里.gitignore匹配到了目标检查.gitignore规则并调整空文件夹没上传成功Git不跟踪空目录添加占位文件如.gitkeepLF will be replaced by CRLFWindows换行符处理警告正常提示无需处理Permission denied (publickey)SSH密钥未配置正确检查公钥是否已添加到GitHub忘了当前在哪个分支分支切换后没有查看git branch -v 查看当前分支这张表基本覆盖了头一个月能用到的坑。遇到报错不要慌先把这个报错信息复制到搜索引擎里搜GitHub相关的报错大概率已经有人踩过千百次了。6. 三个提升推送效率的实用技巧6.1 配置SSH告别每次输TokenHTTPS方式第一次用起来方便但天天push的话每次输入用户名和Token真的很烦。SSH方式一次性配置终身免密强烈建议早点换。整个流程四步走。第一步生成SSH密钥对。在终端执行ssh-keygen -t ed25519 -C 你的邮箱一路回车即可如果需要设置密码口令就输入一个。执行完会在~/.ssh目录下生成两个文件id_ed25519是私钥绝不能给别人看id_ed25519.pub是公钥可以放心公开。第二步查看公钥内容并复制。执行cat ~/.ssh/id_ed25519.pub以ssh-ed25519开头的一长串字符串就是公钥把它整段复制下来。第三步在GitHub上添加公钥。进入Settings → SSH and GPG keys → New SSH keyTitle随便填粘贴公钥保存。第四步把远程仓库地址换成SSH形式。在项目目录执行git remote set-url origin gitgithub.com:你的用户名/仓库名.git之后执行git push第一次会提示是否确认连接输入yes回车之后就全程无感推送了。这一步配好之后配合VS Code等编辑器自带的Git功能体验可以直接对标商用工具的丝滑。6.2 写一个一键推送的小脚本个人项目改动频繁每次重复敲add、commit、push确实会让人烦。我给自己写了一个小脚本放在项目根目录一行参数就搞定提交说明#!/bin/bash # 用法: ./push.sh 提交说明 cd $(dirname $0) git pull origin main git add . git commit -m $1 git push保存为push.sh之后执行chmod x push.sh赋予执行权限。以后改完代码只需要./push.sh feat: 新增用户列表接口脚本会自动先pull拉取远程更新再提交和推送。我在脚本里特意把pull放在最前面是为了减少push被拒绝的可能性。个人练手、自用项目用这个没问题但在多人协作的项目里还是建议手动确认git add了哪些文件脚本一键全量提交容易把临时文件、调试代码一起推上去得不偿失。6.3 图形化工具的选择建议如果命令行一开始让你觉得门槛偏高完全可以用图形化工具过渡。GitHub官方推出的GitHub Desktop是门槛最低的选择界面简洁Commit、Push、Pull都对应着明确的大按钮文件变更列表也很直观适合第一次建立提交、推送、拉取的肌肉记忆。VS Code内嵌的源代码管理面板也非常实用左侧可以看到每个文件的修改状态、diff对比提交和推送都在同一个面板里几乎所有用VS Code写代码的人都会顺手用它处理Git操作。SourceTree这类老牌工具功能更强分支图可视化更清晰但界面信息密度较高新手一上来容易被绕晕。我的建议是前期用GUI工具能让你快速跑通流程但git status、git log、git diff这几个查询命令还是值得花点时间学会。排查问题、写脚本、在服务器上操作仓库时命令行比任何GUI都直接。最终你会发现它通用、快速、不受图形环境限制这也是很多老手最终还是回到终端的原因。最后分享一个小习惯每开始一个新项目第一时间创建一个.gitignore把日常依赖目录、构建产物、环境配置全部排除掉不要等传了一半才想起处理。还有尽量保持一次提交只做一件事提交信息里说清楚做了什么、为什么做。我见过太多人因为提交信息全是update而无法定位历史版本最后只能逐条翻diff硬查。GitHub的学习曲线说陡也陡说平也平跑通你的第一次push后面就顺了。