全栈开发做到第三四个项目的时候你大概率会碰到一个尴尬场景本地代码写得差不多了想放到 Gitee 或 GitLab 上备份、跟进进度结果却卡在“怎么把本地项目推到仓库”这一步。哪怕你已经在 IDE 里跑了无数次代码面对 Git 的命令行还是心里发怵怕一个push下去把仓库搞坏。说实话这个坎太普遍了。Git 上传本地项目到仓库看起来就是几条命令的事但里面牵扯到仓库创建、协议选择、SSH 配置、首次提交、分支推送这一整条链路任何一个环节没理顺都会报出一堆莫名其妙的错误。这篇教程就是给全栈开发入门者准备的我会从安装配置讲起把本地项目推到远程仓库的完整过程一步步拆开也会把我在实际项目里踩过的坑、排过的错一并整理出来。你照着走一遍基本就能把这块彻底拿下。1. 先想清楚为什么全栈开发第一步是学会“拥抱仓库”很多刚入门的同学觉得 Git 是“大厂才用得上的东西”自己写个课程设计、毕设项目根本不需要。但等你真正进入全栈开发的状态就会发现版本控制不是你选不选的问题而是你什么时候开始用的问题。1.1 仓库到底在解决什么痛点我们常说“代码仓库”其实它解决的远不只是“备份”这么简单。我见过太多初学者用一个文件夹装几十个文件命名从“项目最终版”到“最终版改2”再到“打死不改版”最后自己都分不清哪个是当前要用的。Git 仓库的核心思路是把每一次修改都记录成历史快照你随时可以回退、对比还能同时在不同分支上干活互不干扰。举个例子一个全栈项目通常涉及前端、后端、数据库脚本、部署配置。假设你负责后端同事负责前端如果没有仓库两个人只能用网盘传压缩包改完再手动合并——那酸爽我经历过一个下午全耗在文件冲突上。而 Git 仓库可以让每个人在独立分支上开发完成后合并到主干谁改了什么一清二楚。1.2 从开发到上线的链路里Git 卡在哪个环节结合“从开发到上线”这个系列主题来看Git 不是最后部署上线时才开始用的而是从你写好第一行代码就该进入工作流。一个典型链路是这样的本地写代码 →git add暂存 →git commit生成版本快照 →git push推送到远程仓库 → 服务器git pull拉取部署 → 上线。这中间git push就是你最常打交道的动作也是本篇教程的核心。你要是能在本地项目刚起步时就把这套链路跑通后面不管是单独开发还是团队协作都会顺很多。反过来如果你一直拖着不用仓库等代码量上来了再去整理那才是真正的噩梦。2. 环境准备Git 安装与全局配置在讨论怎么上传之前先把基础环境整利索。Git 的安装在不同操作系统上差别不小但都不算难关键是安装完之后的配置环节很多人容易忽略导致后续 push 报错。2.1 Windows / macOS / Linux 下的安装方式如果你用的是 Windows最简单的方式是去 Git 官网下载安装包一路默认选项点到底就行。需要注意的一个点是安装过程中会让你选默认编辑器建议选 VS Code 或者 Notepad别留默认的 Vim否则你以后写 commit 信息时不小心进到 Vim 界面连怎么保存退出都不知道直接被卡住。macOS 上就省事多了装 Homebrew 后跑一行命令brew install git装完验证一下版本git --versionLinux 系以 Ubuntu/Debian 为例用 apt 即可sudo apt update sudo apt install git -y这里我想多说一句很多同学装完 Git 不验证直到使用时才报 “git: command not found”。所以装完立刻跑git --version确认一下是最省心的习惯。2.2 全局用户信息为什么一定要配装好 Git 之后第一件事不是去建仓库而是先告诉 Git“你是谁”。Git 每次提交时会把用户名和邮箱写进本次提交记录里作为身份标识。如果不配置或者配置出错提交时会弹出一堆提示。我用的是代码仓库用户常见的配置方式git config --global user.name 你的名字 git config --global user.email 你的邮箱之所以用--global是因为这些信息对所有仓库都生效省得每个项目都重复配。如果你在某个项目里想用不同身份可以在项目目录内去掉--global再执行一次优先级会覆盖全局配置。检查配置是否生效git config --global --list配置这一步很多人觉得无所谓其实影响很大。你在 Gitee 或 GitHub 上提交代码后需要把本地邮箱和远程仓库绑定的邮箱保持一致提交记录里才能正常显示你的头像和昵称。不然你辛苦提交半天仓库首页显示的是一条没有头像的陌生记录看着就难受。2.3 SSH Key 配置一次配置长期免密上传本地项目到仓库最常用的两种协议是 HTTPS 和 SSH。HTTPS 每次 push 都要输账号密码或者个人访问令牌SSH 配好密钥后可以长期免密我自己更推荐 SSH。需要先声明一点SSH 相关的操作都是在你自己的电脑和代码托管平台之间完成的不涉及任何复杂的网络工具正常学习和工作场景完全能用。生成密钥的方式ssh-keygen -t rsa -b 4096 -C 你的邮箱执行后会提示你确认保存路径可以直接回车用默认的~/.ssh/id_rsa。接着会要求设置密码短语可以直接回车跳过这样以后用起来更省事。生成的公钥在~/.ssh/id_rsa.pub里查看命令cat ~/.ssh/id_rsa.pub然后把一整行ssh-rsa开头的内容复制下来粘贴到 Gitee 的“设置 → SSH 公钥”里标题随便填。添加完成后在本地验证一下ssh -T gitgitee.com如果配置正确会返回欢迎信息。这一步搞定了后面推代码就再也不用输密码了。3. 创建远程仓库以 Gitee 为例的完整流程本地项目要上传首先得有一个“落点”也就是远程仓库。国内开发者用得最多的平台是 Gitee码云操作逻辑和 GitHub 基本一致。这里我以 Gitee 为例把创建仓库的细节掰开来讲。3.1 在 Gitee 上创建仓库的要点登录 Gitee 后点击右上角的“”号选择“新建仓库”。这里有几个关键参数需要注意仓库名称建议与本地项目名保持一致比如mall-system这样本地远程一目了然。路径会自动根据名称生成也可以手动改。仓库描述随意填但建议写清楚项目用途方便团队里的人一眼看懂。还有一个重要的选择是“开源”还是“私有”。如果只是自己学习练手选私有更稳妥如果希望做开源项目、给简历加分那就选公开。这个你可以根据自己的需要定。初始化设置里通常会看到“使用 Readme 文件初始化这个仓库”的勾选框。如果你完全是第一次上传项目这一步建议不要勾选任何初始化选项不勾选 README、不勾选 .gitignore、不勾选开源许可证。原因很简单如果你初始化了文件远程仓库里就有了初始提交本地项目首次 push 时就必须先 pull 拉取合并对新手来说等于多增加一个出错的环节。我的习惯是让远程仓库保持空的状态等本地推上去。3.2 HTTPS 与 SSH两种协议该怎么选创建好仓库后页面会给出两种提交地址HTTPS 地址和 SSH 地址。两者的区别我用一个表格来说明对比项HTTPSSSH首推代码需要输入用户名和密码/令牌配置密钥后免密适用场景临时拉取、一次性使用日常频繁提交、长期维护配置难度不需要额外配置需要生成并添加公钥安全性较高令牌可单独管理很高私钥本地保存我的建议是如果你只是偶尔从远程拉取别人的开源项目用 HTTPS 就够了如果你要长期往自己的项目里推代码那直接走 SSH前面花五分钟配置后面省不知道多少事。拿我自己的经历来说早期我嫌配置 SSH 麻烦一直用 HTTPS结果一两周后 Gitee 要求启用强密码、或者令牌过期push 就反复失败每次都要重新认证。后来花了五分钟把 SSH 配好再也没出过问题。这个前期的“小麻烦”实际是最划算的投资。4. 本地项目上传从 init 到 push 的完整实操环境准备好了、远程仓库也建好了下面进入正题怎么把本地项目真正传到仓库里去。我建议你先在命令行里走通一遍流程搞清楚每一步是干什么的再去用 IDE 的可视化按钮因为只有理解了底层逻辑遇到报错才不至于瞎试。4.1 初始化本地仓库并设置提交信息在项目根目录下打开终端Windows 可以用 Git BashmacOS/Linux 直接终端执行git init这条命令会在当前目录下生成一个隐藏的.git文件夹里面保存着仓库所有的版本记录。执行完你会发现命令行前面多了个(master)或者(main)说明已经进入 Git 管理状态了。如果你的项目里有不该上传的文件比如编译产出、本地配置文件、IDE 自己的工作目录最好先创建.gitignore文件。这个文件的作用是告诉 Git 哪些文件和目录不需要追踪。一个典型的 Java 全栈项目.gitignore长这样target/ *.class *.jar .idea/ *.iml .DS_Store node_modules/ dist/很多新人第一次上传时没写.gitignore结果把本地几百 MB 的依赖包也推上去了仓库瞬间变得臃肿不说别人拉下来还跑不起来。这个文件越早建越好。4.2 暂存、提交与查看状态接下来把项目文件加入暂存区。最简单的方式是用git add .它的意思是把当前目录所有未被忽略的文件都加进来。但这里我想多说一句git add .虽然省事但如果你改了很多文件且分属不同功能最好还是分开 add这样每个提交记录的意义更清晰。git add . git status执行git status后你会看到哪些文件被标记为“Changes to be committed”绿色的就是已暂存状态。确认无误后执行首次提交git commit -m 项目初始化完成基础框架搭建代码大概是这个意思但提交信息要按你的实际内容来写。我强烈建议commit信息别写“update”“修改”这种废话最好是一句话能说清楚这次提交做了什么。比如“修复登录接口空指针异常”就比“修改bug”有价值得多后面翻历史记录时你会感谢自己。4.3 关联远程仓库并推送本地提交完成之后需要把本地仓库和远程仓库关联起来。假设你在 Gitee 上复制的是 SSH 地址执行git remote add origin gitgitee.com:你的用户名/mall-system.gitorigin是远程仓库的默认别名你也可以叫别的名字但业界约定俗成都用origin没必要特立独行。关联后可以查看远程仓库信息git remote -v确认地址没问题再执行推送。第一次推送时因为本地分支默认叫master部分环境是main远程仓库还是空的所以带上-u参数意思是把本地分支和远程分支建立追踪关系git push -u origin master如果之前本地分支叫main那就改成git push -u origin main。推送成功后刷新 Gitee 页面就能看到你本地项目的全部文件出现在远程仓库里了。4.4 IDEA 里上传本地项目的可视化操作命令行版本走通之后如果你平时主力用的是 IntelliJ IDEA也完全可以走可视化操作。IDEA 自带的 Git 集成非常强大步骤也不难。首先用 IDEA 打开你的项目确保 Settings 里的 Git 路径已经正确指向安装目录。然后选择 VCS → Enable Version Control Integration选择 Git 作为版本控制工具。这会自动执行相当于git init的操作。接着项目文件会变成红色或绿色右键项目根目录 → Git → Add把文件加入暂存区。然后右键 → Commit Directory填写提交信息后提交。最后通过 Git → Push 推送到远程仓库如果还没配置远程地址IDEA 会提示你输入远程 URL粘贴 Gitee 仓库地址就行。我个人经验是命令行和 IDE 操作并不是对立的。排查问题、处理复杂合并时命令行更高效日常提交用 IDE 更直观。两条腿走路才是成熟开发者的状态。5. 分支与协作上传只是开始进阶操作很关键当你成功把本地项目推到仓库意味着已经迈出了第一步。但一个真正的全栈项目很少只有一个人开发所以分支管理和团队协作这块也得尽快补上。5.1 创建分支与合并分支的基础思路分支是 Git 中最核心也最精华的概念。简单理解分支就是一条独立的工作线你在自己的分支里改代码不会影响到别人的工作。等你的功能写完了再合并回主干。创建并切换新分支git checkout -b feature-login这条命令相当于两条命令的合并git branch feature-login创建新分支git checkout feature-login切换过去。在新分支里正常修改、提交完成后切回主分支git checkout main把新分支合并进来git merge feature-login我在实际项目中通常遵循一个原则主干分支永远保持可上线状态新功能一律在分支里开发完、测试通过后再合并。这样即使某个分支做砸了直接删掉重来对主干没有任何影响。5.2 git commit --amend 的正确使用姿势热词里有人问到git commit --amend这里也单独说一下。这个命令的作用是“修改最近一次提交”可以改提交信息也可以把新的修改追加到上一次提交中去。如果你只是想把上次的提交信息改一下git commit --amend -m 新的提交信息如果你想补充遗漏的文件git add 遗漏的文件 git commit --amend --no-edit--no-edit表示沿用原来的提交信息不重新编辑。但这里必须提醒一句amend会改变提交历史如果这提交已经推送到远程仓库而别人已经基于它拉了分支那你 amend 之后本地历史和远程就对不上了这种情况下别硬推需要谨慎处理。如果还没推远程或者是你独自维护的分支放心用没问题。5.3 多人协作时遇到冲突的应对话术合并分支时最让人头疼的就是冲突。假设你和同事改了同一个文件同一块代码Git 没法自动判断保留哪边就会提示冲突。此时打开冲突文件你会看到类似这样的标记 HEAD 你本地改的内容 远程分支的内容 feature-login你需要手动保留需要的部分删掉冲突标记保存文件。然后重新 add、commit完成合并。我第一次遇到冲突时慌得不行后来经验多了就淡定了冲突本身不可怕它只是 Git 的一种保护机制让你有意识地决定代码最终长什么样。6. 常见错误与排查实录这块是我最想分享的。初学者遇到的报错翻来覆去就那么几个你把下面这几类问题提前看一遍后面能少走很多弯路。6.1 fatal: not a git repository 类错误这个报错的字面意思是当前目录不是 Git 仓库。常见原因有两个一是你还没执行git init二是你在子目录里执行命令但 Git 仓库在上一级目录。排查命令很简单pwd ls -a看当前路径下有没有.git目录没有就回到项目根目录再操作。这类报错往往不是大问题但会打断心流提前清楚原因能省不少时间。6.2 推送被拒远端已有提交记录或认证失败你第一次向空仓库推送时如果看到 “failed to push some refs”通常是远程仓库里已经有文件了比如你在创建仓库时勾选了 README 初始化。此时本地和远程的历史互不相干Git 不允许直接覆盖。解决办法是先把远程内容拉下来合并git pull origin master --allow-unrelated-histories--allow-unrelated-histories允许两个完全独立的历史合并在一起。合并后如果有冲突按 5.3 节的方法解决再重新 push。但说实话最省事的办法还是前面说的创建仓库时别勾选初始化文件从源头避免这个问题。还有一种常见情况是 HTTPS 方式推送时提示认证失败。这时候建议直接换成 SSH 方式或者去 Gitee 生成个人访问令牌用令牌代替密码。6.3 上传了不想传的文件怎么办如果你发现自己不小心把本地的大文件或者敏感文件推上去了第一步是赶紧把它在远程仓库删除然后加入.gitignore防止之后再次上传。删除远程保留本地的操作git rm -r --cached 文件或目录名 git commit -m 移除误传的文件 git push这里的关键是--cached它表示只从 Git 追踪记录里移除不会删除你本地磁盘上的文件。这个技巧在处理误传文件时非常管用。6.4 使用技巧速查场景命令或操作查看当前状态git status查看提交历史git log --oneline --graph撤销暂存区文件git restore --staged 文件名修改最近提交信息git commit --amend -m 新信息推送新分支到远程git push -u origin 分支名拉取远程更新git pull origin main强制推送慎用git push --force写在最后的实操心得我见过太多人学 Git 的时候只记住几条命令用完就忘下次换个场景又开始查文档。其实 Git 的核心逻辑就那么几条工作区改代码、暂存区挑文件、本地仓库存快照、远程仓库做同步。你只要把这条流水线刻在脑子里上面的所有命令都只是在不同的环节操作而已。个人建议今天就把你手头最常用的那个项目传到仓库里去哪怕它还不成熟。传完之后试着把某个文件改一改再 commit 一次push 上去然后假装自己搞砸了执行一次git log找到之前的版本用git checkout切回去看看。这整套动作下来你就能真正体会到 Git 到底在帮你什么。至于服务器上、团队协作里的更多玩法包括分支策略、CI/CD 自动拉取构建都是一步步在真实项目里补上的。但今天把上传本地项目到仓库这个起点跑通了后面的一切才有得谈。