我记得有一次在高铁上赶一个紧急迭代，网络时断时续，远程仓库推不上去，分支还改到一半。旁边同事急得直跺脚，我却能照常提交、切分支、做版本回滚——因为我的Git仓库就活在本地，网络只是锦上添花，不是必需品。很多人一提到Git就想到GitHub、GitLab，觉得没网就玩不转，这其实是对Git最大的误解。Git的核心是一个本地代码管理工具，它的仓库、提交、分支、回滚全部在你自己的磁盘上完成。换句话说，只要你的电脑活着，开发就能继续。
这篇文章就是围绕这个很多人忽略的事实展开的。我会从为什么本地代码管理值得重视开始，讲清楚Git在无网环境下的完整使用逻辑，再覆盖安装配置、常用命令、分支合并、IDEA集成，以及一个几乎所有人在接远程仓库时都会遇到的SSH认证失败问题。无论你是刚接触Git的新手，还是用了一段时间但总觉得"没网就没法干活"的老手，这篇文章都能帮你把本地这条线彻底打通。
1. 为什么离线开发反而能逼出好习惯——本地仓库的核心价值
聊聊我对Git的第一印象。刚入行的时候，我也以为Git就是那个绿色的猫头鹰图标网站，每天的工作就是pull和push，哪天推送失败就觉得天塌了。直到有一次公司内网故障，远程仓库彻底连不上，我才被迫开始研究本地仓库，也就是在那次断网经历里，我真正理解了Git的设计哲学。
1.1 Git不等于GitHub，本地仓库才是根基
Git是一个分布式的版本控制系统，这个"分布式"三个字是关键。它意味着每一个仓库副本都是完整的，包含全部历史记录、全部分支、全部版本信息。你第一次执行git init的那一刻，一个完整的版本库就在你的项目目录里诞生了，它不欠任何服务器什么。
GitHub也好，GitLab也罢，本质上只是Git的一个托管站点，是别人帮你维护的一个远程备份和中转站。它们提供的PR、Issue、Code Review等功能确实香，但这不是Git本身的功能。打个比方：Git是一台单反相机，照片存在你自己的存储卡里，只要拍下来了就不丢；GitHub是相册平台，你可以把照片传上去备份、分享，但传不上去的时候，你相机里的照片一点都不会少。
想通这一点以后，我养成了一个习惯：任何项目，不管将来要不要上远程，第一件事永远是git init，先把本地仓库立起来。因为本地仓库不仅仅是防丢，它更是一个允许你自由试错的时间机器。
1.2 不需要联网的完整工作流是什么样子
很多人习惯的工作流是：改代码 → push到远程 → 当作备份。这个习惯在没有网络的时候就会断档。但如果你理解本地仓库的独立性，你的工作流就会变成这样：
- 改代码，随时git add、git commit，提交记录全部存本地
- 想实验新方案，就创建分支，随便折腾，不行就删掉，不影响主干
- 改坏了，随时git reset回滚到任何一个历史提交
- 网络恢复了，一次性把本地积累的提交推到远程
这个模式的好处不只是"没网也能干活"，更重要的是它改变了你的提交习惯。以前我为了凑一次push，经常攒了一大堆改动才提交一次，提交信息乱七八糟，回滚的时候想死。现在我把提交粒度拆得很细，每完成一个小的功能点就commit一次，因为提交是本地操作，零成本，所以反而更愿意频繁提交。
1.3 本地代码管理解决的真实痛点
我可以负责任地说，本地管理这套能力，在有网环境下依然是救命稻草。举几个我亲身经历的场景：
- 给客户做私有化部署，客户环境是物理隔离的内网，什么远程仓库都连不上，全靠本地Git维护历史版本
- 一个实验性的技术方案，还没想好要不要给团队看，在本地分支里折腾了好几周，随时可以回到起点
- 线上出紧急Bug，你在客户现场改的热修复代码，远程认证服务器刚好抽风，提交不了，但你能在本地完成所有版本操作，等网络稳定再推
这些场景的共同点就是：远程仓库只是备份和协作手段，本地仓库才是你真正的作战阵地。所以接下来的所有内容，我都会围绕"本地优先"这个视角来展开。
2. 装好Git只是开始：各平台安装细节与全局配置
我知道你们很多人已经装了Git，但装完以后就再没管过配置。这一章不只是教你怎么装，更想聊聊那些装完必须立刻设置、否则后续踩坑的配置项。
2.1 三大平台的安装要点
Windows、macOS、Linux的安装方式其实都很成熟，我只挑容易出问题的点说。
Windows上，去Git官网下载安装包，一路Next就行。但有一个选项很多人忽略：安装向导会让你选默认的换行符处理方式。诚心建议选第一项"Checkout Windows-style, commit Unix-style line endings"，也就是提交到版本库时统一转成LF换行。跨平台项目里最恶心的就是换行符问题，Windows和Linux混用会导致整个文件被判定为修改，选这个默认项能从根上避开80%的坑。
macOS用户注意，如果你的Mac装了Xcode Command Line Tools，系统自带的Git版本可能比较老。建议直接用Homebrew装新版：brew install git。装完以后用git --version确认一下。
Linux用户最简单，发行版包管理器直接装就行，但Ubuntu这类长期支持版本自带的Git版本通常偏旧，遇到问题时优先考虑从源码编译或加官方PPA，而不是在旧版上死磕。
2.2 全局配置不做好，后面全白搭
装完之后第一件事，配置用户名和邮箱。这是Git提交记录的署名，不配置的话，你提交代码的时候Git会拿系统主机名拼一个奇怪的默认身份，后续代码审查根本对不上人。
git config --global user.name "你的名字" git config --global user.email "你的邮箱" git config --global init.defaultBranch main git config --global core.autocrlf true第三行是设置默认分支名为main，避免老版本默认创建master。新项目用main作为主分支名，既避免和"主从"这种历史用语的歧义，也和主流托管平台的默认设置对齐，省得每次都要mv分支。
2.3 编码和编辑器配置：中文乱码的根源在这
在国内开发环境里，Windows上乱码问题几乎人人遇到。核心是三个层面的编码设置。让Git对中文文件名和中文提交信息友好一点：
git config --global core.quotepath off git config --global gui.encoding utf-8 git config --global i18n.commit.encoding utf-8第二个坑是Git调用外部编辑器时中文输入乱码。如果你打算用命令行提交并写中文提交信息，最好把默认编辑器换成VS Code或Notepad++这类支持UTF-8编码的工具：
git config --global core.editor "code --wait"code --wait的意思是用VS Code打开编辑器，并且等文件关闭后才继续执行命令。这样你git commit的时候，Git会启动VS Code，你写好提交信息、保存并关闭，Git才会完成提交操作。
2.4 GUI工具要不要装
我个人推荐新手可以装一个GUI工具作为辅助，但命令行的基本功不能丢。SourceTree、Fork、Tower各有拥趸，不过我最推荐的其实是VS Code自带的源代码管理器，因为它跟你写代码的窗口无缝集成，学习成本最低。
但你要明白，GUI工具只是把命令行的操作变成了按钮，如果你看不懂按钮背后对应的Git命令，一旦遇到冲突、回滚这种复杂场景，照样抓瞎。所以我下面几章的讲解会以命令行为主，同时告诉你每个操作在GUI里的位置，两条路线并行，理解会深得多。
3. 本地仓库从零到一：核心命令与工作流
第一节我们说了本地仓库是根基，这一节就来实操。你需要在任何时候都能不看文档，完成一套完整的本地版本管理。
3.1 初始化仓库和第一次提交
进入项目目录，执行：
git init它会创建一个.git隐藏目录，这就是版本库的所在地。在这个目录里，Git会记录所有文件的快照、提交历史、分支指针等信息。再执行：
git add . git commit -m "初始化项目"git add .把所有文件加入暂存区，git commit把暂存区的快照固化成一个版本。理解这两个命令的区别很重要。add相当于把要打包的文件挑进收纳箱，commit才是真正封箱归档。你可以多次add，然后一次commit，这样提交信息就可以准确概括这一批所有改动。
这里我要强调一个新手最容易掉进去的坑：git add .很容易把不该提交的文件打进去，比如IDE的配置目录、编译生成的target目录、node_modules这些。Git的设计哲学是提交什么由你决定，所以必须学会用.gitignore文件来明确告诉Git哪些东西永远不用管。
3.2 gitignore的正确姿势
一个合格的.gitignore文件，应该包含三类内容：操作系统产生的垃圾文件（比如.DS_Store、Thumbs.db）、IDE/编辑器的个人配置（.idea、.vscode）、构建产物和依赖（node_modules、target、dist、*.class等）。我一般会在项目根目录放一个基础版：
.DS_Store .idea/ .vscode/ node_modules/ dist/ target/ *.log有个经验之谈：gitignore的规则匹配的是目录和文件的路径模式，target/表示忽略所有名为target的目录，而不只是根目录下的。这种写法则灵活又省心。
3.3 查看状态和历史：status和log
可以用这两个命令了解当前仓库状态：
git status git log --oneline --graph --allgit status看工作区现在的状态，哪里改了、哪些还没提交，一目了然。git log --oneline --graph --all看全部提交历史，--graph会画出分支的树状结构，--all会把所有分支的提交都显示出来，排查问题的时候经常用。想看得更细就加-p参数，会展示每次提交的完整差异，这是代码审查和排查Bug的神器。
3.4 撤销和回滚：本地仓库的后悔药
这可能是本地管理最值钱的能力。工作区改坏了，用：
git restore 文件名把文件恢复到最近一次提交的状态。想撤掉某次提交但保留它的改动在本地，用：
git reset --soft HEAD~1 git reset --mixed HEAD~1--soft撤销提交但保留改动的暂存状态，--mixed撤销提交并且取消暂存，但改动还在工作区。区别就是你想不想让那些改动继续等着被重新commit。如果改动完全不要了，用git reset --hard HEAD~1，这个命令会把工作区也一起重置，务必确认好用，因为改动会彻底消失。
还有一个更安全的回滚命令是git revert，它的原理是生成一个反向提交来抵消目标提交，不改变历史记录，适合在多人共享的分支上操作。但在纯本地环境下，我更喜欢直接reset，因为本地分支历史只有你自己看，reset会让历史更干净。这也是本地管理的自由度：你对历史拥有完全的掌控权。
4. 分支不是摆设：离线场景下的分支管理与合并
分支是Git最强大的设计之一，也是很多人用了很久却没真正用明白的功能。记住一件事：分支在Git里只是一个指向某次提交的指针，创建分支、切换分支全部是本地实时操作，连网络都不需要。
4.1 分支的本质和常用操作
创建并切换分支：
git branch feature/login git checkout feature/login # 或者一条命令搞定 git switch -c feature/login像git switch这种比较新的命令，明显比老式的checkout语义更清晰。git branch列出全部分支，当前分支前面有星号。你需要理解的核心概念是：每次切换分支，Git会把工作区的内容恢复成那个分支最新提交时的样子。
这带来一个非常实用的能力：你可以同时推进多个互不干扰的实验。比如业务开发进行到一半，突然有一个新想法，你可以切到另一个分支去试，不行就切回来。由于每个分支的提交历史完全独立，你在main分支的代码不会受影响。离线环境下的分支就更像导演手里的分镜脚本，可以随时抽出来单独打磨。
4.2 合并分支与冲突处理
开发完功能，把分支合回主干：
git checkout main git merge feature/loginGit会把feature分支的改动合并进来。合并有两种结果：一种是能自动合并，因为两边改的文件互不重叠，Git会自己搞定；另一种是产生冲突，常见于两个人改了同一文件同一区域，Git无法判断到底要哪个版本。
冲突并不可怕，可怕的是很多人不知道处理冲突的标准流程。当git merge提示CONFLICT时，用编辑器打开冲突文件，你会看到类似这样的标记：
<<<<<<< HEAD 这是当前分支的内容 ======= 这是被合并分支的内容 >>>>>>> feature/login你需要做的是人工判断，删除这些标记，保留想要的内容，然后保存文件。特别注意：千万不能在没删除标记的情况下提交，否则Git会把冲突标记留在代码里。全部处理完以后：
git add . git commitGit会生成一个合并提交。如果是本地合并，你完全可以在一个没人围观的环境里慢慢处理冲突，这也是离线开发的一个隐性优势：心态更稳。
4.3 简洁的本地分支协同策略
很多人觉得分支管理很复杂，其实在本地或小团队场景，一条极简策略就够了：main分支永远保持可发布状态，每次开发一律从main切出新分支，功能做完测试通过再合并回main。
我第一次带项目的时候，后端同事直接把所有功能和修复全堆在main分支上，结果线上要紧急修Bug又不想带上没做完的功能，愁得不行。从那以后我就强制推行"创建临时分支 + 完成后合并"的模式，收益立竿见影。单独本地管理时，这个策略会让你的历史像一条干净的主线偶尔带几个弯道，看log的时候非常直观。
5. IDEA里玩转本地Git：新建项目、拉取与提交
命令行归命令行，但日常写代码大概率还是在IDE里，IDEA对Git的集成做得相当完善，合理使用可以让操作效率再上一个台阶。这里我以IDEA为例，因为它的内置Git支持覆盖了几乎全部常见场景。
5.1 用IDEA创建新项目并初始化本地仓库
很多人用IDEA新建项目之后，会去GitHub上先建一个空仓库再克隆下来，这是一条绕远的路。更直接的做法是：在IDEA里从零开始创建或打开项目，然后通过菜单VCS → Enable Version Control Integration → 选择Git，IDEA就会在当前项目目录执行git init。
接着你需要做的第一件事就是创建一个.gitignore文件。IDEA有个贴心的功能，右键项目根目录 → New → .ignore file，会弹出模板选择器，勾选Java、Maven（或你用的技术栈）等选项，IDEA会帮你生成一份包含常见忽略规则的.gitignore，比手写省事很多。
然后通过快捷键Ctrl+K提交文件，第一次提交之前记得确认右下角弹出的是你配置好的Git账户信息。
5.2 从已有仓库拉取项目
遇到"IDEA创建新项目拉取Git"这种需求，实际上就是克隆一个已有的远程仓库，然后用IDEA打开。最稳妥的方式是：先用命令行git clone，再用IDEA的Open功能选择这个目录。为什么我更推荐命令行？因为你可以在克隆的时候顺便确认网络、认证、分支状态都正常，而IDE的克隆对话框报错信息往往不够直观。
git clone git@github.com:yourname/yourproject.git克隆完成之后，用IDEA打开目录，IDEA会自动识别出这是一个Git项目，右下角的分支信息、文件颜色标识都会正常工作。
5.3 IDEA里最常用的三个Git功能
日常开发里，IDEA内部这三个功能用得最频繁：
Ctrl+K（Commit）：提交窗口，左侧是文件改动列表，右侧是diff对比，下方是提交信息输入框。每行diff都可以勾选是否包含在本次提交里，这比命令行git add粒度更细。Ctrl+Shift+K（Push）：推送提交到远程。但在纯本地模式下往推，这个按钮会提示没有配置远程仓库，完全不用管，你的提交依然稳稳地存在本地。VCS → Git → Branches：分支管理弹窗，可以看所有本地分支、创建新分支、切换分支、合并分支，操作全部图形化。
我个人的习惯是：日常代码增删和提交用IDEA的UI，涉及复杂的reset、rebase、以及多分支操作时回到命令行。两条路都要会，因为有些极限场景是IDE搞不定的，比如git reset --hard在IDEA里要打开Log窗口右键提交记录选择Reset Current Branch，操作路径藏得比较深，还是命令行来得痛快。
5.4 一个小技巧：IDEA的Local History能当备用时间机器
最后说到IDEA，很多用户不知道它的Local History功能。即使项目还没有纳入版本管理，IDEA也会在本地自动记录代码文件的历史改动。右键任意文件 → Local History → Show History，就能看到先前版本的快照并一键恢复。
但要注意：Local History的保留时间和文件量都有限制，而且它依赖IDE的本地缓存，清了缓存就没了。所以它可以作为Git的临时替补，但永远不能替代真正的Git仓库管理。真正的版本管理还得靠Git的提交记录。
6. SSH认证失败？这是远程协作场景下最常见的坑与排查链路
聊到这里，我们得正视一个现实：虽然本地开发可以完全离线进行，但绝大多数项目最终还是要和远程仓库打交道的。而"ssh认证失败 git"这个问题的出现频率，简直高到离谱。这一节我完整复盘一次排查过程，这也是我觉得写出来对大家最有帮助的部分。
6.1 一个真实的SSH认证失败现场
有一天早上，同事发消息说公司新换的GitLab地址，他重新克隆代码提示权限禁止。我先让他把完整报错发过来，内容是：
git@gitlab.example.com: Permission denied (publickey).这句话的字面意思是：服务器收到了连接请求，然后拒绝了，原因是密钥验证失败。权限拒绝发生在服务器端，但根因几乎都在客户端，也就是你的本机密钥配置有问题。
6.2 逐步排查的完整链路
第一步，确认本机有没有生成过密钥：
ls ~/.ssh/看下这个目录里有没有id_rsa和id_rsa.pub这两个文件。没有的话要重新生成。
ssh-keygen -t rsa -b 4096 -C "你的邮箱"一路回车，除非你想给密钥设密码。生成之后在~/.ssh/下就会出现一对公私钥。注意吗，公钥是.pub后缀，这个是要给服务器那边登记的；私钥没有后缀，必须自己保管好，绝不要传出去。
第二步，把公钥内容复制到托管平台的SSH配置里。不同平台入口不同，GitHub是Settings → SSH and GPG keys，GitLab是Preferences → SSH Keys。复制公钥用这个命令：
cat ~/.ssh/id_rsa.pub把输出内容整个粘贴到平台的钥匙输入框中，保存。注意：粘贴的时候要完整复制，一行都不能少，末尾换行有时候漏了也不行。
第三步，测试连接：
ssh -T git@gitlab.example.com这里的地址换成你实际使用的托管平台域名。如果看到类似"Hi username! You've successfully authenticated"的信息，说明认证成功了。如果仍然提示Permission denied，进入第四步。
第四步，检查本机是否以正确身份连接。这里有一个极易被忽视的坑：本机的~/.ssh/config文件里可能为另一个平台配置了默认IdentityFile，导致Git连接时用了错误的私钥。你可以用详细模式看当前用哪个密钥文件：
ssh -Tv git@gitlab.example.com输出里会有一行"Offering public key: ..." 显示的是实际读到密钥的路径。如果发现读到的是别人家的密钥，就在config里增加一段，为这个平台指明正确的密钥：
Host gitlab.example.com HostName gitlab.example.com User git IdentityFile ~/.ssh/id_rsa6.3 权限问题：Windows和macOS上的细节补充
Windows用户要特别注意家目录权限。微软在OpenSSH里继承了严格的权限检查机制，如果C:\Users\你的用户名\.ssh目录权限太宽松（比如Users组有完全控制权限），SSH会直接拒绝使用这个目录下的密钥。修复方法是右键.ssh文件夹 → 属性 → 安全 → 高级，把继承关掉，只保留当前用户的完全控制权限。
macOS用户注意钥匙串的问题。macOS会把私钥的密码存进钥匙串里，如果你改过密码或钥匙串里存的是旧密码，认证也会失败。这种时候删掉钥匙串里对应的Git条目，重新执行git命令让它重新读取密码即可。
6.4 认证失败时，本地开发凭什么不受影响
这是本章最想传达的观点，也是回到本文主题的核心逻辑。即使SSH认证一直失败，远程仓库暂时推不上去，你也完全不需要停下来。你的提交历史、分支、回滚、版本对比全在本地照常运作，唯一不能做的就是push和pull。
我的建议是：发现remote仓库问题的时候，先保持冷静，本地继续把开发做完、提交干净，再花时间排查SSH。如果问题一时半会解决不了，可以用git bundle把本地仓库打包成一个文件，拷贝到有网的机器上再推远程。这一点上我又要强调一次：Git的本地性不是退路，而是日常开发的主路径，远程仓库只是你愿意公开的那份镜像。
回到开头那个高铁上的场景，对我来说，"无需联网也能高效开发"从来不是一句宣传口号，而是我每天都在用的工作方式。真正理解Git的本地基因之后，你会发现失联不再是事故，而是常态。把本地仓库维护好、分支理清楚、提交做干净，你会发现代码开发这件事，绝大部分时间其实都可以不需要网络。希望这篇文章能帮你把这条路也走通。
