Git 加 Gitee 这套组合我在项目里用了六七年。标题里的“从入门到实战”看着宽泛其实落到日常开发就是一条清晰的主线把本地代码安全地推到远程仓库再把远程的更新拉回来中间处理好分支、冲突和免密认证。这篇文章我按自己实际踩坑的顺序来写从零开始装 Git、配密钥、建仓库、推代码一直到分支合并和常见报错排查每一步都给结论、给命令、给原因。不管你是刚接触版本控制的学生还是已经在用 IDE 内置 Git 功能但没搞懂底层逻辑的开发者照着走一遍都能把整套链路跑通。1. 整体思路拆解先搞懂 Git 和 Gitee 各自扮演什么角色很多教程一上来就让用户复制命令结果出了问题完全不知道去哪排查。我的建议是先把两个工具的分工搞清楚后面所有操作都围绕这条主线展开。1.1 核心概念版本库、暂存区、工作区到底是什么意思Git 是分布式版本控制系统和 SVN 那种集中式管理最大的区别在于每个开发者本地都有一份完整的仓库历史。也就是说即使远程服务器挂了你本地依然能提交代码、查看历史、回滚版本这在断网环境下特别实用。Gitee 的角色是远程托管平台相当于一个多端同步的“中央节点”提供代码存储、权限管理、Issue 跟踪、Pages 部署这些能力你和队友的本地仓库通过它来交换数据。我们再拆一层。Git 的本地仓库内部逻辑上分三个区域工作区你正在编辑的文件目录、暂存区通过 git add 把改动放进去的区域好比购物车、版本库通过 git commit 把暂存区内容固化成历史记录的地方。日常操作可以概括为在工作区改文件用 add 挑选要提交的改动用 commit 生成一个不可变的快照再用 push 把快照同步到远程。理解这个链路之后遇到“明明改了文件但提交不进去”“提交了但远程没变化”这类问题就能快速定位是卡在哪个环节。1.2 为什么选 Gitee 而不是其他平台很多人会问既然 Git 本身是开源的为什么不直接用 GitHub。对于一个国内开发者来说Gitee 有几个非常实际的优点服务器在国内clone 和 push 的速度明显更快不需要额外手段就能稳定访问支持一键导入 GitHub 仓库迁移成本很低提供的 Gitee Pages 功能可以免费托管静态站点适合做个人博客或项目文档展示。当然 GitHub 在开源生态和社区资源上依然不可替代我的习惯是 GitHub 放对外开源项目Gitee 放国内协作项目和个人备份两者通过远程仓库地址切换就能共存互不干扰。配合 Web IDE 或 JetBrains 系 IDE 的内置 Git 插件使用时Gitee 也提供了完整的 OAuth 授权流程首次连接授权一次之后后续操作基本是透明的。但我不建议新手一上来就依赖图形界面因为图形界面会隐藏真实命令遇到报错时你连错误信息都看不懂。先用命令行把核心流程走一遍再用 IDE 的图形按钮会顺手很多。2. 环境准备与初始化从零安装到 SSH 免密登录这一节解决的是“本地环境怎么搭起来”的问题。很多人卡在第一步不是不会敲命令而是安装选项选错了、环境变量没生效、密钥没配对导致后面步步出错。2.1 Windows 环境下的 Git 安装细节去 Git 官网下载 Windows 版本安装包时注意选择 64-bit 版本下载速度慢的话可以找国内镜像。安装过程中大部分步骤保持默认即可但有两个地方值得停下来看一眼。第一个是“选择默认编辑器”默认是 Vim如果你之前没用过 Vim建议在这里改成 VS Code 或 Notepad否则以后执行 git commit 需要编辑提交信息时会因为不知道怎么退出 Vim 而卡住。第二个是“调整 PATH 环境变量”一定选“Git from the command line and also from 3rd-party software”这样 Git 的命令才能同时被 CMD、PowerShell 和 IDE 识别。第三步“配置行尾转换”默认选第一个“Checkout Windows-style, commit Unix-style line endings”这个对跨平台协作很重要Windows 和 Linux 的换行符不一样Git 会在检出和提交时自动转换避免整个文件被标成改动。安装完成后打开 Git Bash输入git --version能输出版本号就说明安装成功。这时候我建议顺手把默认分支名设成 main新建仓库时的初始分支就是它和 Gitee 平台默认分支保持一致省得后面还得改git config --global init.defaultBranch main2.2 全局身份配置用户名和邮箱是提交记录的“签名”Git 每次提交都会记录作者信息这个信息来自全局配置。设置方式很简单git config --global user.name 你的名字 git config --global user.email 你的邮箱这里有个常被忽略的细节邮箱不一定要用真实邮箱但最好用你在 Gitee 账号上绑定的那个邮箱。因为 Gitee 会通过邮箱把提交记录关联到账号如果邮箱不一致你的提交在平台上会显示成“无名氏”。验证配置是否生效git config --list输出里能看到 user.name 和 user.email 就说明配置成功。如果你同时维护多个身份比如公司 GitLab 和个人 Gitee可以去掉 --global 参数在某个仓库目录内单独配置这样该仓库会用局部配置覆盖全局配置。2.3 SSH 密钥配置为什么每次都输密码会让人崩溃用 HTTPS 协议连接远程仓库每次 push 和 pull 都要输入账号密码虽然可以记住凭据但在命令行环境里体验很差。SSH 密钥方式则是一劳永逸客户端持私钥Gitee 服务器存公钥传输时通过密钥对完成身份验证不需要输入任何账号信息。生成密钥的第一步是检查是否已有现成的ls -al ~/.ssh如果看到 id_rsa 和 id_rsa.pub 这类文件说明之前生成过可以直接用没有的话执行ssh-keygen -t ed25519 -C 你的邮箱我推荐用 ed25519 算法它比传统的 RSA 密钥更短、生成更快、安全性更高。一路回车接受默认路径即可。如果设置了 passphrase私钥口令每次使用 SSH 时会要求输入一次不想麻烦就直接留空。然后把公钥内容复制出来cat ~/.ssh/id_ed25519.pub登录 Gitee进入“设置 — 安全设置 — SSH 公钥”把输出的内容粘进去标题随意填。添加完成后验证ssh -T gitgitee.com看到提示“Hi XXX! Youve successfully authenticated”就说明密钥配对成功。这里请注意Gitee 的 SSH 地址是 gitgitee.com端口默认 22如果所在网络封了 22 端口可以在 ~/.ssh/config 里加一段配置改走 443 端口Host gitee.com Hostname gitee.com Port 443这个技巧在部分受限网络环境下实测有效。3. Gitee 仓库创建与本地关联完整走通一次推送流程环境准备好之后进入实战环节。这一节我按“建仓 — 关联 — 提交 — 推送”的顺序讲顺便把分支和合并这两个高频操作也说清楚。3.1 创建远程仓库时容易忽略的几个选项登录 Gitee 后点击“新建仓库”需要填写的信息有仓库名、路径、是否私有、初始化设置等。仓库名建议用英文小写加横线分隔比如 wechat-miniapp-demo避免中文和空格因为 URL 里包含仓库名中文会转成编码串既丑又容易出错。私有/公开根据项目需要选个人练习项目选私有即可不影响功能使用。往下拉到“选择开源许可证”和“使用 .gitignore 初始化”这两个选项。许可证如果拿不准就选 MIT它最宽松别人可以自由使用你的代码只要保留版权声明。 .gitignore 文件的作用是排除不需要纳入版本控制的文件编译产物、IDE 配置文件、依赖目录等Gitee 提供了各种语言的模板选择你的主语言会自动生成。注意一个使用习惯问题如果勾选了“使用 Readme 文件初始化”仓库会自动生成一个 README.md 和初始提交之后你本地仓库关联时会出现“远端已有提交、本地还没有”的冲突。我的习惯是建仓时不勾选任何初始化选项保持仓库完全空白让本地作为第一个提交的源头这样关联更干净。还有一个小知识点Gitee 仓库默认不允许在仓库根目录直接创建子仓库也就是嵌套仓库会显示为普通目录无法单独管理版本。如果确实需要在一个项目里维护多个独立模块比较规范的做法是使用 Git 的 submodule 功能后面的小节我会讲。3.2 本地仓库初始化与远程关联的三种路径假设你已经在某个项目目录里写了一些代码现在要把它纳入 Git 管理并在 Gitee 上备份。进入项目目录后git init git add . git commit -m init projectgit init 会在当前目录生成 .git 文件夹这是 Git 的灵魂所在。git add . 会把当前目录所有文件加入暂存区注意这里受 .gitignore 规则限制。git commit 生成第一个本地提交。接下来添加远程仓库地址git remote add origin gitgitee.com:你的用户名/仓库名.gitorigin 是远程仓库的默认别名你也可以改成别的名字但约定俗成都叫 origin。添加完后用 git remote -v 查看关联情况。首次推送时执行git push -u origin main-u 参数的意思是把本地 main 分支和远程 main 分支建立追踪关系之后直接敲 git push 就能推送到对应分支。第二种路径是先从远程克隆别人已经在 Gitee 上建好了仓库你要拿到本地。命令是git clone gitgitee.com:用户名/仓库名.git克隆会自动完成初始化、关联远程、检出默认分支这三步不需要手动 init。第三种路径是本地目录已存在但你想换成另一个远程地址比如从旧地址迁移到新仓库git remote set-url origin 新地址改完之后 push 即可本地提交历史会完整保留。3.3 分支管理从创建到合并的完整闭环分支是 Git 最核心的能力之一。简单理解分支就是一条独立的开发线在一个分支上提交代码不会影响其他分支。日常开发流程通常是在 main 分支上拉出 dev 开发分支开发完再合并回 main。常用命令git branch dev # 创建 dev 分支 git checkout dev # 切换到 dev 分支 git checkout -b dev # 创建并切换相当于上面两条的合体 git branch -a # 查看所有本地和远程分支在 dev 分支上做了几次提交之后要合并回 maingit checkout main git merge dev如果 main 分支没有新的提交这个合并是“快进合并”历史会变成一条直线。如果两边都有新提交Git 会尝试自动合并但可能会产生冲突。冲突产生的原因是两个分支修改了同一个文件的同一块区域Git 不知道该听谁的。冲突时文件里会出现类似这样的标记 HEAD 这是当前分支的内容 这是被合并分支的内容 dev你需要手动编辑这个文件决定保留哪边或者都保留删掉标记后保存然后git add 冲突文件 git commit -m resolve conflict很多人刚接触冲突时会慌实际上冲突并不可怕它只是 Git 在告诉你“需要人类做决策”。关键是不要在有冲突时强行提交先解决再走流程。分支合并之后如果 dev 分支不需要了可以删除git branch -d dev删除远程分支用git push origin --delete dev3.4 submodule一个仓库里管理独立子项目之前提到过一个常见问题Gitee 仓库能不能包含子项目答案是Git 本身支持用 submodule 实现但需要注意它的使用方式。比如你的主项目依赖另一个独立仓库你可以把后者作为子模块引入git submodule add gitgitee.com:用户名/子项目.git src/lib这条命令会克隆子项目到指定目录并在主仓库里记录它的 commit 版本。别人克隆你的主仓库后需要执行git submodule update --init --recursive才能把子模块内容拉下来。submodule 的坑在于它默认不自动同步子模块的更新如果子项目有了新提交你需要进入子目录拉取更新再回到主仓库提交一次把新的子模块版本号记录更新。理解这点之后用起来基本不会出大问题。4. 实战高频场景与疑难杂症排查最后一个大节我看重讲日常用 Git 时最常踩的坑。这些报错我在工作里几乎每周都会遇到网上提问量也很大干脆整理成速查表配上排查思路。4.1 常见报错速查报错信息、原因、解法报错关键字常见原因解法fatal: not a git repository当前目录不是 Git 仓库在项目根目录执行 git init或确认是否进入了正确的目录ssh: Permission denied (publickey)SSH 公钥未添加到 Gitee或本地私钥不可用重新生成密钥并添加公钥用 ssh -T gitgitee.com 测试fatal: remote origin already exists已经关联过远程仓库用 git remote remove origin 删除后重新关联failed to push some refs远程有本地没有的提交先 git pull 拉取合并再重新 pusherror: src refspec main does not match any本地还没有任何提交先 git add 和 git commit再执行 pushfatal: unable to access 仓库地址网络无法连接远程检查网络、改用 SSH 地址或使用国内镜像地址排查的基本原则报错信息里带 “fatal” 的基本都是可以自行修复的问题先读完整错误信息再到搜索引擎搜最后一行关键字比盲目试命令高效得多。这里专门说一下 fatal: not a git repository 这个报错。它出现的场景通常是你在某个子目录里执行 git status而这个子目录没有被 Git 跟踪。注意Git 的仓库范围是以包含 .git 文件夹的目录为边界的子目录默认属于仓库范围但如果你在子目录里手动执行了 git init就会生成一个嵌套的 .git变成一个“游离仓库”。如果真的不小心执行了删除子目录下的 .git 文件夹即可恢复。4.2 大文件推送失败超过平台限制该怎么处理Gitee 平台对单个文件的大小有限制超过 20MB 的文件直接 push 会报错。很多人第一反应是问有没有配置项能放宽限制实际上这是平台侧的硬性限制本地改什么都没用。处理大文件的正规思路是使用 Git LFSLarge File Storage。启用方式git lfs install git lfs track *.psd git add .gitattributes git add 大文件 git commit -m add large file git pushGit LFS 会把大文件的实际内容替换成一个指针文件存入仓库大文件本体单独存储其他协作者 clone 时按需拉取。不过 Gitee 的 LFS 有容量和流量限制免费额度不大。如果项目里大文件非常多我更推荐换一种策略把大文件放网盘或对象存储仓库里只保留下载链接和校验值。这样既不影响版本控制也避免撑爆仓库体积。顺带提一个常见误区有人想通过加大提交缓冲区来推送大文件git config http.postBuffer 524288000这个配置只对 HTTP 协议下的传输缓冲区生效解决的是“通信中断”而非“文件超限”问题对 Gitee 的硬性大小限制没有任何作用不要指望它。4.3 修改提交信息与撤销操作commit --amend 等技巧的用法git commit --amend 这个命令的实际用途是修改最近一次提交的 commit message也可以把少量新改动并入上一个提交。比如刚提交完发现 message 打错字git commit --amend -m 修正后的提交信息如果你只是忘记在提交里包含某个文件的改动可以先 add 这个文件再执行 git commit --amend这样新改动会并入上一个提交不会多出一条提交记录。有一点必须提醒amend 的本质是替换了原来的提交对象所以只应该用于尚未推送到远程的提交。如果提交已经 push 到远程再修改后强行 push 会破坏远端历史导致协作者仓库状态不一致。这时候宁可新开一个提交也不要 amend。另外几个高频撤销命令git reset --soft HEAD~1 # 撤销提交但保留改动在暂存区 git reset --hard HEAD~1 # 撤销提交同时丢弃改动 git checkout -- 文件名 # 丢弃工作区的未提交改动reset --hard 非常危险它会彻底丢弃改动且无法恢复。执行前先用 git log 查看提交记录确认要回退的版本号。4.4 Gitee Pages把仓库变成静态网站Gitee Pages 是平台自带的静态网站托管服务适合给项目做说明文档、个人主页或者博客。使用方法很简单在仓库的“服务”菜单里找到“Gitee Pages”选择部署分支通常是 master 或 main和目录一般是根目录点击启动。部署完成后你会得到一个类似 https://用户名.gitee.io/仓库名/ 的地址。部署的两个注意点第一Pages 服务需要实名认证否则无法开启第二每次更新了仓库内容Pages 不会自动更新需要回到 Pages 页面手动点击“更新”按钮。这个“手动更新”机制经常被新手忽略以为部署一次就万事大吉了。如果你希望自动部署可以配置 Gitee 的 WebHooks 配合 CI 服务或者使用 GitHub Actions 推送 GitHub 仓库后由 Gitee 同步仓库再触发 Pages 构建。这个链路配置稍复杂但对需要频繁更新文档的朋友来说非常值得。4.5 IDE 集成IDEA 和 VSCode 连接 Gitee 的两种姿势大部分现代 IDE 都内置了 Git 客户端不需要在命令行和界面之间来回切换。以 IntelliJ IDEA 为例首次连接 Gitee 时在设置里添加 Gitee 账号推荐选择 SSH 方式IDE 会自动读取你本地的私钥无需重复配置。创建新项目并推送到 Gitee 的流程是在 IDEA 里把项目根目录初始化为 Git 仓库VCS - Enable Version Control Integration然后 commit 代码接着在项目右键菜单里找到 Git - GitHub/Gitee - Push 或 Share on Gitee填写仓库名后即可完成关联和首次推送。VSCode 用户可以在扩展市场安装 GitLens 和 Git Graph前者增强 diff 和 blame 体验后者能在时间线图里直观看到分支走向和提交节点特别适合理解分支合并逻辑。VSCode 自带的源代码管理面板已经覆盖了 add、commit、push、pull 这些基础操作。我的建议是日常开发用 IDE 按钮节省时间但每个按钮背后对应什么命令要心里有数。这样遇到按钮点了没反应、报错看不懂的时候切换到终端跑一下真实命令往往能立刻看到具体错误信息排查效率会高很多。4.6 团队协作与代码审查的基础规范多人协作时光会命令还不够还得定好协作规范。最基础的一条不要直接在 main 分支上开发。每个功能或修补都应该开一个独立分支命名可以参照 feat-登录模块、fix-支付bug 这类格式让人一看就知道这个分支的用途。分支合并前至少过一遍 diff确认没有误删改别人的代码再合入。协作过程中保持提交粒度小一点也很重要。一个提交只做一个逻辑改动commit message 用动词开头的简短描述例如“fix: 修复订单金额计算错误”而不是“bug修复”这种废话。这样 git log 刷出来就像一份清晰的开发日志回溯问题的时候能快速定位到具体提交。如果在团队里使用 Gitee还可以开启 Pull Request 审查模式。开发分支推到远程后在 Gitee 网页上发起 Pull Request指定审查人审查通过后再合并。这个过程虽然没有 GitHub 那么重的社区氛围但作为小型团队的代码质量关卡已经足够用。写到最后分享几个我自己的使用习惯工具这东西用得久了自然会有一些属于自己的“肌肉记忆”。我在实际开发中保留了几个习惯写在这里给大家参考。第一个习惯是每次开始新功能前先执行 git pull 把远端最新代码拉下来再创建本地分支而不是基于一个过时的 main 分支开发。这样能规避掉大量不必要的合并冲突。第二个习惯是提交前用 git diff 检查一遍改动这个动作能拦住很多低级错误比如把调试用的 console.log 或写死的本地路径提交上去。很多人提交之后才发现问题再 amend 或个人 undo 一条条回退费时费力。第三个习惯是给 .gitignore 建立一个从项目开始就维护的规则集合把 node_modules、target、dist、.idea、.vscode 这些目录全部排除。新同事克隆代码后能直接运行不会把一堆本地生成文件带到 Git 历史里。最后一个建议定期练习一次“删除本地仓库再重新克隆”的完整恢复流程。这个操作能帮你检验自己的备份是否可靠同时也逼着你把提交记录做得清晰。等到你熟练到能在一分钟内恢复一个干净的开发环境Git 对你而言就不再是障碍而是真正顺手的工具了。