很多人第一次接触 GitHub都是从“想把自己写的代码放上去”这个念头开始的。我自己当年也是这样对着命令行一头雾水搞不清 commit 和 push 到底什么关系也闹过把整个文件夹拖进网页却上传失败的尴尬。后来用得多了才明白GitHub 初学阶段只要把“上传、修改本地项目文件到 GitHub”这条主链路走通后面那些复杂功能都是顺水推舟的事。这篇我就不聊虚的专门把从 0 到 1 的操作讲透包括本地项目怎么传上去、文件改了之后怎么同步更新、遇到问题怎么排查。适合完全零基础的初学者也适合那些用过一段时间但一直靠图形界面、没搞懂背后逻辑的朋友。1. 先搞清楚Git 和 GitHub 到底在干吗1.1 版本控制是个啥很多新手一上来就敲命令敲完也不知道自己在干嘛。其实 Git 解决的核心问题只有一个记录版本。想象你在写一篇论文最开始叫“论文终版.doc”改了两天后变成“论文终版2.doc”后来又变成“论文最终版3.doc”。这种文件名后缀的写法本质上就是一种最原始的版本管理只不过它非常痛苦你想找回三天前删掉的一段话基本只能靠回忆或者靠 Word 里的“撤销”。Git 做的事情就是在你的项目目录里搞一个隐藏的仓库每次你想留个节点就执行一次提交commitGit 会把当前所有文件的快照存下来并且记录这次提交是谁、在什么时间、改了什么内容。以后任何时刻你都可以回退到这个节点或者对比两个节点之间到底改了哪些文件、哪些行。对于写代码的人来说这意味着你可以大胆尝试各种改动改崩了随时回到上一个正常版本。这就是版本控制的价值它让“后悔药”变成了日常工具。1.2 本地仓库、远程仓库和那几条常用命令Git 是本地工具GitHub 是托管平台。你用 Git 在本地管理项目然后把项目的提交记录同步到 GitHub 这个远程仓库上。打个比方Git 像是你电脑上的草稿本GitHub 是帮你把草稿本的内容抄写到云端展示和备份的地方。围绕这个核心最常用的命令就三个动作git add把改动放进暂存区相当于告诉 Git“这些文件我准备记录了”。git commit把暂存区的内容正式提交成一个版本相当于拍照存档。git push把本地的存档同步到 GitHub 远程仓库。再加上一个反向动作git pull把远程仓库的更新拉到本地。整个 Git 学习阶段九成时间都在和这四个命令打交道其他的都是在这条主线上扩展出的细节。你不需要急着背命令先理解它们之间的关系后面边用边记自然就熟了。2. 准备工作装 Git、注册账号、配置 SSH2.1 不同系统下怎么安装 Git在开始操作之前电脑上得有 Git。如果用的是 Windows推荐直接去 Git 官网下载安装包一路“Next”装完中间有一个步骤会问调整 PATH 环境变量保持默认的 “Git from the command line and also from 3rd-party software” 即可。安装完成后打开任意终端cmd 或 PowerShell输入git --version能输出版本号就说明装好了。macOS 用户更省事。终端里执行git --version系统如果提示没有安装会弹出安装 Command Line Developer Tools 的窗口点确认等它装完就行。你想用 Homebrew 装也可以命令是brew install git。Linux 用户一般用发行版自带的包管理器比如 Debian/Ubuntu 上执行sudo apt install gitCentOS 上用sudo yum install git。这里要注意装完后最好也执行一次git --version验证一下省得后面命令报“command not found”时才回头排查环境变量问题。2.2 配置用户名和邮箱Git 装好后要做两件事告诉 Git 你的名字和邮箱以及生成 SSH 密钥。名字和邮箱会写进每一次提交记录里方便别人知道是谁改的代码。打开终端执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这里 --global 表示全局生效也就是这台电脑上所有仓库默认都用这个身份。如果你只想对某个项目单独设置可以去掉 --global在项目目录里重新执行一遍。检查配置是否生效运行git config --list就能看到当前所有配置项。2.3 生成 SSH 密钥并添加到 GitHubSSH 密钥相当于一把“钥匙”让本机和 GitHub 之间建立信任关系这样以后推送代码就不需要反复输密码。现在生成密钥推荐用 Ed25519 算法比老式的 RSA 更安全GitHub 也完全支持。在终端里执行ssh-keygen -t ed25519 -C 你的邮箱执行后会出现提示让你确认保存路径直接按回车使用默认的~/.ssh/id_ed25519即可。接着会问你要不要设置 passphrase密钥口令这个随便你设了口令更安全但每次用的时候要多输一次密码不设的话回车跳过就行。生成完成后找到公钥文件。Windows 用户通常在C:\Users\你的用户名\.ssh\id_ed25519.pubmacOS/Linux 在~/.ssh/id_ed25519.pub。用文本编辑器打开它复制里面的内容。登录 GitHub点击右上角头像进入 Settings在左侧菜单找到 SSH and GPG keys点 New SSH key标题随便填一个比如“我的电脑”然后把刚才复制的公钥粘到 Key 文本框里点 Add SSH key 保存。验证是否配置成功回到终端执行ssh -T gitgithub.com如果看到类似Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.的提示就说明 SSH 已经通了。这一步做完后面所有 push 和 pull 都会很顺畅。3. 第一次上传本地项目从零推到 GitHub3.1 在 GitHub 上新建一个远程仓库本地项目想传到 GitHub你首先得有一个“接收”它的地方。登录 GitHub 后点页面右上角的加号选 New repository。仓库名建议用英文和短横线比如my-first-project描述可填可不填。然后选择可见性Public 是公开的任何人都能看到Private 是私有的只有自己和被你授权的协作者能看到。对于练习项目选 Private 更保险避免不小心把代码公开出去。这里有一个新手特别容易踩的坑创建仓库时GitHub 会默认询问你是否要添加 README、.gitignore 或者许可证。如果你本地已经初始化了项目那这三个选项千万不要勾选直接点 Create repository 建一个完全空的远程仓库。因为一旦远程仓库里有 README而本地仓库没有等下推送时会因为两边历史不一致而报错虽然能解决但没必要额外增加操作负担。3.2 本地项目初始化并提交假设你本地有一个项目文件夹里面是你要上传的代码。打开终端进入这个目录cd 你的项目路径第一步执行git init这个命令会在当前目录里创建一个隐藏的.git文件夹意味着这个目录正式变成 Git 仓库。第二步用git add .把项目里所有文件加进暂存区。注意这个点.代表当前目录下的所有文件如果你想只添加某个子文件夹可以写git add 文件夹名比如git add src。执行完后用git status看一下暂存区状态会列出所有即将被提交的文件。如果确认没错执行第一次提交git commit -m first commit-m后面的内容是你给这次提交写的说明第一次提交写 “first commit” 就行。此刻本地仓库已经有了第一个版本。3.3 关联远程仓库并推送现在需要把本地仓库和 GitHub 上的远程仓库关联起来。在刚才新建仓库的页面上GitHub 会给出几行提示其中一种就是通过 SSH 关联。按照提示执行git remote add origin gitgithub.com:你的用户名/仓库名.git这里的origin是远程仓库默认的名字相当于给这个 URL 起了一个别名以后推送时不需要每次都写一长串地址。关联完可以用git remote -v查看确认 URL 没有写错。接下来在推送之前要先确定分支名。GitHub 现在默认分支叫main但老版本的 Git 初始化仓库时默认分支可能是master。为了统一规范本地先执行一条改名命令git branch -M main-M的意思是强制改名哪怕当前分支是 master 也会把它改成 main。然后推送git push -u origin main-u参数让本地 main 分支和远程 main 分支建立追踪关系以后你在这个分支下只要直接输入git push和git pullGit 就会自动知道该和哪个远程分支同步。第一次推送时终端可能会提示确认 SSH 指纹输入yes回车即可。看到类似main - main和Branch main set up to track origin/main的输出刷新一下 GitHub 仓库页面代码就已经躺在那了。3.4 上传文件夹时的细节处理很多人的本地项目不只是几个文件而是一个包含多层文件夹、资源文件、图片、配置文件的项目。Git 本身对文件夹没有特殊待遇它针对的是每一个文件。如果你执行git add .所有文件夹里的文件都会被递归加入暂存区最终完整地推到 GitHub 上这一点不需要额外操作。但有一个例外空的文件夹不会被 Git 管理。如果你的项目里有个空目录希望它保留在仓库中常见做法是在里面放一个内容可为空的.gitkeep文件这样 Git 就会把这个目录纳入管理。还有一个关键问题你未必想把所有文件都传上去。比如node_modules这种依赖目录体积巨大而且别人拿到项目后可以靠npm install重新生成完全没有提交的必要还有.env这类包含密钥或密码的配置文件传到 GitHub 上等于泄露敏感信息。这时候就需要在项目根目录创建一个.gitignore文件把不需要管理的文件或目录写进去。一份基础模板如下# 依赖目录 node_modules/ # 环境变量文件 .env # 编译产物 dist/ build/ # 操作系统生成的文件 .DS_Store Thumbs.db # 日志文件 *.log写完保存后再执行git add .时这些被忽略的文件就不会出现在暂存区里了。4. 后续修改本地文件改了之后如何同步到 GitHub4.1 日常更新的三步走项目传上去之后你不可能就此收工日常的开发过程就是不断改代码、提交、推送。假设你本地已经有一个和远程关联好的仓库现在你修改了项目里的README.md想把这个改动同步到 GitHub操作流程非常固定git status git add README.md git commit -m 更新README文档 git push先执行git status看看哪些文件被改动过然后用git add把需要提交的文件加入暂存区接着git commit生成一次提交记录最后git push推到远程。如果修改的文件很多或者你确定要提交当前文件夹下所有改动也可以把git add README.md换成git add .一次性处理。对于初学者我建议每次提交前用git status看清楚自己到底改了哪些文件避免把不该提交的东西加进去。4.2 新增文件、删除文件的同步方式新增一个文件并同步时操作和修改差不多。新建文件后系统会提示 untracked file你需要先git add 新文件名或git add .把它纳入 Git 管理然后 commit、push。删除文件的处理则有两种常见方式一种是手动在资源管理器里删除文件后在 Git 里执行git rm 文件名 git commit -m 删除无用的旧文件 git push另一种是如果已经删除了文件Git 会在git status里标记为 deleted你只需要git add .或git add -uGit 就会把这个删除动作记录到暂存区然后照样 commit、push。注意git add -u只会处理已经被 Git 追踪的文件不会把新增但未追踪的文件加进来所以如果你既新增了文件又删除了文件我还是建议直接用git add .一步到位。4.3 远程有更新时先拉取再推送如果在另一台电脑上你也提交过代码或者你参与了别人的项目本地推送前最好先检查一下远程仓库是否有了新提交。GitHub 网页端如果提示你的分支落后于远程或者本地 push 时出现 “rejected” 的报错通常都是因为远程有本地没有的提交。这时候执行git pull origin main这个命令会把远程更新的内容合并到本地。默认情况下如果远程修改的文件和你本地修改的文件不是同一个位置合并会很顺利Git 会自动处理好。如果是同一个文件的不同位置也有概率自动合并如果实在是同一行的冲突Git 会在文件里用特殊标记指示冲突区域需要你手动编辑保留哪一部分。编辑完冲突后再执行git add和git commit完成合并。这里还有一个进阶选项git pull --rebase origin main。普通的 pull 在合并时会产生一个额外的 merge commit历史记录看起来会有一条分叉曲线加上--rebase后Git 会把本地提交“摘下来”在远程最新提交之后重新放上去历史记录会是一条直线更干净。对于新手我建议先不用纠结默认git pull就够了等用熟了再决定要不要 rebase。4.4 改错了怎么回退改代码过程中难免手滑学会回退也是必修课。如果是文件还没执行git add你想放弃本地对这个文件的全部修改让文件回到最近一次提交时的样子git restore 文件名如果已经git add进了暂存区但还没 commit你想取消暂存但保留文件改动可以用git restore --staged 文件名如果想撤销最近一次提交但希望保留改动继续编辑可以用git reset --soft HEAD~1其中HEAD~1表示上一个提交。这些命令足够应对日常回退了。强烈建议新手不要在一个分支上轻易尝试git reset --hard这个命令会直接丢弃工作区里未提交的改动一旦执行很难找回来。安全问题操作前最好用git status确认一下工作区状态。5. 常见问题与排查技巧实录5.1 Permission denied 和认证失败第一次连接 GitHub 时执行ssh -T gitgithub.com如果提示Permission denied (publickey)说明 SSH 密钥没有正确配置。排查方向很明确第一确认本地公钥是否已经添加到 GitHub第二确认用的是不是正确的那把钥匙如果生成密钥时自定义过文件名Git 默认找不到第三确认仓库远程地址用的是 SSH 而不是 HTTPS。查看远程地址用git remote -v如果是https://github.com/...开头的可以用git remote set-url origin gitgithub.com:用户名/仓库名.git改成 SSH 地址。如果你用的是 HTTPS 地址推送并且提示要求输入密码请注意 GitHub 很久之前就不再支持账号密码直接推送了。现在必须使用 Personal Access Token个人访问令牌在 GitHub 的 Settings - Developer settings - Personal access tokens 里生成生成时勾选repo权限。复制这个 token在推送输入用户名时输入你的 GitHub 用户名密码栏粘贴这个 token 即可。5.2 推送被拒绝non-fast-forward这个报错对新手来说出现频率极高。原因非常简单远程仓库里有你本地没有的最新提交而你的本地提交基于的是旧的历史记录。Git 出于安全考虑不允许直接覆盖远程的更新所以会拒绝推送。解决方法前面已经提过git pull origin main拉取合并后再推送。如果你确定远程的更新你都不需要才考虑git push -f强制推送但需要注意这会覆盖远程历史影响非常严重尤其是多人协作时千万不要乱用。我在教学里见过太多人在这个阶段慌掉以为代码丢了其实只是远程比你多了东西拉下来就好。5.3 误提交了敏感文件或大文件如果已经不小心把.env文件提交并推送到了 GitHub即使你在.gitignore里把它忽略并且删除了文件历史记录里依然保留着这个文件的旧版本别人如果克隆了整个仓库还是能看到。正确做法是用git rm --cached把文件从跟踪列表里移除但保留本地文件git rm --cached .env git commit -m 移除敏感文件 git push但这只对后续的提交有效历史里的旧版本仍然存在。要彻底清理历史需要用到git filter-branch或git filter-repo这样的高级工具对新手来说比较复杂。我的建议是从一开始就在提交之前认真检查git status和.gitignore尤其是涉及密钥、密码、token 的文件一旦推到远程就要立刻去 GitHub 页面把该令牌作废防患于未然。5.4 中文文件名显示成转义字符在 Git 里如果文件名包含中文默认情况下git status会把中文显示成\346\265\213\350\257\225.txt这样一串八进制转义字符看着非常难受。解决方法是把 Git 的 quotePath 设置为 falsegit config --global core.quotepath false设置成功后中文文件名就能正常显示了。这个问题不解决也不影响代码存储但排查文件改动时会很难受所以建议提前配置好。6. 我平时用 Git 时的一些习惯和小技巧聊完了操作和排错最后分享几个我这些年用下来的习惯不算什么高深技巧但对新手少踩坑很有帮助。第一个习惯是提交信息写清楚“为什么”。不是让你写长篇大论而是至少别写 “update” 这种毫无信息量的话。“修复登录接口空指针问题”和“update”给未来的自己看是完全不同的体验。已经提交了不合规范的说明也没关系只要下次写好就行Git 本身并不在意。第二个习惯是频繁提交而不是攒一大堆变更一次性 commit。提交越频繁历史回退的粒度就越细定位问题也就越容易。哪怕只改了十几行代码只要它代表一个完整的逻辑变更就可以提交。我的经验是一次提交只做一件事这样你的提交历史会像一本清晰的开发日记。第三个建议是给你的常用命令设置别名。比如我把git status简化为git stgit log --oneline --graph简化为git lg执行效率会高很多。设置别名的方法git config --global alias.st status git config --global alias.lg log --oneline --graph设置后输入git st就相当于git status输入git lg就能看分支提交图。关于学习路径我建议刚开始别急着折腾 Git 的高级功能先把 add、commit、push、pull 这几个命令练成肌肉记忆同时多用git status和git log观察仓库状态。很多新手一上来就问怎么处理 “merge conflict”结果基础命令还不熟所以反而更焦虑。等你把上传和修改这条链路走顺了后面再接触分支、stash、rebase 这些进阶操作会轻松很多。