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 git@gitee.com看到提示“Hi XXX! You've successfully authenticated”就说明密钥配对成功。这里请注意，Gitee 的 SSH 地址是 git@gitee.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 project"git init 会在当前目录生成 .git 文件夹，这是 Git 的灵魂所在。git add . 会把当前目录所有文件加入暂存区，注意这里受 .gitignore 规则限制。git commit 生成第一个本地提交。
接下来添加远程仓库地址：
git remote add origin git@gitee.com:你的用户名/仓库名.gitorigin 是远程仓库的默认别名，你也可以改成别的名字，但约定俗成都叫 origin。添加完后用 git remote -v 查看关联情况。首次推送时执行：
git push -u origin main-u 参数的意思是把本地 main 分支和远程 main 分支建立追踪关系，之后直接敲 git push 就能推送到对应分支。
第二种路径是先从远程克隆：别人已经在 Gitee 上建好了仓库，你要拿到本地。命令是：
git clone git@gitee.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 分支上做了几次提交之后，要合并回 main：
git 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 git@gitee.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 git@gitee.com 测试 |
| fatal: remote origin already exists | 已经关联过远程仓库 | 用 git remote remove origin 删除后重新关联 |
| failed to push some refs | 远程有本地没有的提交 | 先 git pull 拉取合并，再重新 push |
| error: src refspec main does not match any | 本地还没有任何提交 | 先 git add 和 git commit，再执行 push |
| fatal: 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 LFS（Large 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 对你而言就不再是障碍，而是真正顺手的工具了。
