1. 为什么每个开发者都应该亲手配置一次 GitGit 这个东西说句实话刚接触的时候很容易被绕晕。我在带新人的时候经常遇到这样的情况代码写得好好的一提交就出幺蛾子要么是用户名不对导致提交记录显示成别人的名字要么是 SSH 密钥配了半天连不上远程仓库要么是分支名还是老一套的 master跟团队规范对不上。很多人会觉得 Git 配置嘛装完就行了用默认设置就行了。这个想法其实是个大坑。Git 的默认配置只是让你“能用”离“好用”还有一段距离。我自己刚工作那会儿就是吃了这个亏当时公司代码仓库用的是自己搭的 GitLab 实例我第一次提交代码的时候没配 user.name 和 user.email结果提交记录里显示的是一个奇奇怪怪的系统默认名字后面想改还得用 filter-branch 这种高危操作去重写历史别提多狼狈了。所以这次记录一下完整的 Git 配置步骤不是那种官方文档式的流水账而是我实际配过的、踩过坑的、验证过靠谱的流程。包括 Windows、macOS、Linux 三个平台的安装方式基础的全局配置SSH 免密登录以及一些能显著提升效率的进阶配置。无论你是刚入行的新人还是用了多年 Git 但配置基本都是默认状态的老人这篇文章都能给你一些参考。配置 Git 这件事本身并不难但它的价值在于你只需要花十几分钟把环境配好后面每天工作节省的时间远超这十几分钟。别小看这些基础工作团队的协作效率往往就卡在这些细节上。2. 安装这一步做对了后面能省一半的事2.1 Windows 平台安装的两个关键选项Windows 上装 Git 基本就是去官网下载安装包然后一路 Next。但有几个选项是很多人没注意到的我在这里单独说一下我每次都会特意勾选的地方。第一个是编辑器选择。安装到 Select Default Editor 这一步时默认是 Vim。你如果平时不用 Vim看到那个界面真的会崩溃——每一次提交报错需要编辑提交信息的时候卡在 Vim 里出不来。我建议直接选 “Use Visual Studio Code as Gits default editor”前提是你装了 VS Code。不想装 VS Code 的话选 Notepad 也行总之别用 Vim除非你真的会用。第二个是分支名初始化。新版 Git 安装器有个 Choosing the default branch name for new repositories 选项默认情况下 Git 官方已经改成了 main 分支但如果你装的版本比较老需要手动选一下或者装完之后用命令设置。这个后面在全局配置部分会讲。安装完成之后记得在命令行里验证一下版本确认环境变量有没有生效git --version如果提示找不到命令大概率是环境变量 PATH 没配上。重新打开一个终端窗口再试一次一般 Windows 下安装器会自动配好但如果遇到问题需要手动把 Git 安装目录下的 cmd 文件夹加到 PATH 里。2.2 macOS 和 Linux 的安装差异macOS 上装 Git 最简单的方案是装 Xcode Command Line Tools在终端里敲git --version会自动弹出安装提示装完之后 Git 就有了。但这个版本往往不是最新的如果你需要用新特性建议用 Homebrew 装brew install gitLinux 的话要看发行版。Debian/Ubuntu 系用 aptRedHat/CentOS 系用 yum 或 dnfsudo apt update sudo apt install git一个很重要的建议能用系统包管理器装的就用包管理器装别自己去源码编译。我早期装东西特别喜欢折腾源码编译 Git 也不是没干过但后期升级、卸载、维护都非常麻烦。包管理器一键搞定而且依赖关系也都处理好了。另外还有一个被忽略的问题自带的版本可能偏低。比如有些 LTS 版本的系统仓库里 Git 版本还停留在 2.17 左右这在 2025 年来说已经太老了。如果遇到这种情况可以用官方维护的 PPAPersonal Package Archive源来装新版或者直接下载预编译的二进制包替换。配置这个东西能省事就省事。2.3 安装完成后第一件事确认 CRLF 和编码很多人装完 Git 就直接开始用结果第一行代码就遇到“行尾符”问题。Windows 下默认情况下 Git 会把仓库里的 LF 自动转成 CRLF 再放到工作区提交的时候再从 CRLF 转回 LF。安装器在 Configuring the line ending conversions 这一步会问你选哪种方式。我推荐选默认的第一项Checkout Windows-style, commit Unix-style line endings。但要注意如果你的团队里有人是 macOS 或者 Linux而项目里有 Shell 脚本或者 Python 脚本CRLF 会把脚本搞挂。这算是一个历史遗留的经典坑网上相关的讨论一搜一大把。具体治本的办法不是靠安装选项解决而是靠仓库里的.gitattributes文件统一规范这个不在今天配置的范围内但你要知道这个问题存在。安装阶段的选项选默认的就好因为全局配置阶段还有更细的调整空间。3. 全局配置这些命令不是背的是理解着用的3.1 身份信息配置首次提交前必须做的两件事Git 的全局配置保存在用户主目录下的.gitconfig文件里所有仓库默认都读这个配置。核心配置就两条git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的名字和邮箱必须是你代码托管平台GitHub、GitLab、Gitee 等上验证过的邮箱。为什么因为提交记录里的邮箱会关联到你的账号头像如果用了没验证的邮箱你的提交在平台上就显示成一个灰色的无头像、无链接的“路人甲”影响非常直观。另外要注意公司内网的 GitLab 如果和企业邮箱绑定了那 user.email 一定要填企业邮箱否则代码平台不识别权限校验可能出问题。我见过有人用私人邮箱提交到公司仓库结果自动化流水线因为无法识别用户身份直接拒绝构建。3.2 配置文件和命令优先级搞清楚一件事就能避免很多困惑Git 配置有三个层级的存放位置优先级从高到低分别是层级配置文件位置作用域优先级仓库级.git/config当前仓库最高全局级~/.gitconfig当前用户所有仓库中间系统级/etc/gitconfig系统所有用户最低日常开发中全局配置管你的身份信息、默认编辑器、别名这些通用内容仓库配置管特定项目的分支策略、远程地址这些个性化内容。这意味着什么比如你手头有个项目需要用特定的签名密钥那就进到这个项目的目录用不加--global的git config命令设置cd /path/to/project git config user.name 用户名这样设置之后这个仓库会优先使用仓库级的配置覆盖全局配置。这个机制很有用我一般会在公司项目仓库里显式设置一遍身份信息避免全局配置变更时影响公司仓库的提交记录。配置完之后想确认生效情况用这个命令git config --list这个命令会把三层配置合并后的结果都列出来如果输出太长了看不清也可以这样过滤git config --list | grep user3.3 默认分支名main 还是 master建议从配置层统一Git 官方在 2020 年起就默认使用 main 作为初始化分支名但如果你用的版本比较旧或者系统里的模板配置了 master那么每次git init创建的新仓库还会是 master。全局配置一条命令即可解决git config --global init.defaultBranch main这一步的意义在于团队协作时所有人在本地git init得到的默认分支在同一个频道上不会出现你推 main、他推 master、最后合并还得绕一圈的情况。新增这种习惯成本极低但减少的沟通成本非常明显。3.4 默认编辑器和差异对比工具的实际作用默认编辑器除了在提交信息输入时会用到之外还有一个重要场景rebase 交互式操作的时候你需要在一个文本编辑器里编辑一系列命令。用 Vim 的时候真的很容易卡在无操作上效率很低。我现在的配置是这样git config --global core.editor code --waitcode --wait是 VS Code 提供的参数意思是等待编辑完关闭窗口后才继续执行后续命令。如果你喜欢别的编辑器把对应的命令行打开方式替换掉即可。除了编辑器还有合并冲突时用的 diff 工具也可以配置不过这个更多是个人偏好配置不配置看需求比如git config --global merge.tool vscode这行的意义在于当你遇到合并冲突的时候执行git mergetool会拉起图形化工具而不是在终端里盯着和标记硬看。对于不习惯看终端冲突标记的同事来说这一步体验提升特别大。3.5 换行符和编码设置跨平台协作的隐藏杀手团队里 Windows 和 macOS/Linux 混着用如果不处理换行符经常会出现“明明没改这个文件Git 却提示有改动”的奇怪问题。绝大多数时候这是 CRLF 和 LF 相互转换导致的。全局配置一个行为规范git config --global core.autocrlf input这个配置的意思是说提交到仓库时把 CRLF 转成 LF但检出时不强制转回 CRLF。在 macOS 和 Linux 上这个配置没问题在 Windows 上如果你用input模式工具可能会有极少数场景下的适配问题但总体问题不大。再配合一个关键配置避免文件名和提交信息乱码git config --global core.quotepath false不设置这条的话当你提交带中文文件名的文件时Git 状态显示是一串\346\265\213\350\257\225这种转义字符看提交记录看得你怀疑人生。设置成 false 之后中文文件名能正常显示。4. SSH 密钥配置不用每次推送都输密码4.1 为什么要配 SSH Key 而不是每回都用 HTTPSGit 操作远程仓库有两种常用协议HTTPS 和 SSH。HTTPS 的意思就是每次 push/pull 都可能需要输入账号密码虽然可以借助系统自带的凭据管理器记住密码但它在多设备协同、命令行操作频繁的场景下还是不够流畅。SSH 是通过密钥对来认证身份只要把公钥放到代码托管平台本地存好私钥之后所有推送拉取都不需要再输密码。我个人更推荐 SSH 方式原因有这几个不需要在 URL 里暴露账号信息不需要反复输入密码或管理凭据缓存自动化脚本友好可以按设备撤销访问权限在平台后台删掉某个设备的公钥即可4.2 密钥生成的正确姿势生成密钥的命令如下ssh-keygen -t ed25519 -C 你的邮箱或备注这里选ed25519算法是因为它比老式的 RSA 4096 更安全、性能更好而且 GitHub、GitLab 都已经支持很长时间了。如果你因为某些特殊原因只能用 RSA那就这样ssh-keygen -t rsa -b 4096 -C 你的邮箱或备注执行后终端会问你要保存位置默认是~/.ssh/id_ed25519接着会问你要不要设置 passphrase。这一步我建议设置一个虽然每次使用可能会要你输入一次但用ssh-agent这个程序帮你保管的话就方便很多了。如果直接敲回车不设 passphrase 也不是不行只是私钥泄露了相当于账号白送。我曾经吃过这个亏有次出差笔记本被偷好在我给私钥设了 passphrase远程仓库的代码才没被拷走。安全这个事平时看着麻烦关键时刻救命。生成完成后用这个命令查看公钥cat ~/.ssh/id_ed25519.pub把输出的内容复制下来粘贴到代码托管平台的 SSH Key 设置页面里名称随意比如“我的办公电脑”。4.3 ssh-agent 和大内存私钥的加载如果你按照我上面的建议设置了 passphrase那么每次 Git 操作要输一次密码会觉得烦解决办法是用ssh-agenteval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519第一条命令是启动后台代理第二条是把私钥添加到代理中输入一次 passphrase之后在当前终端会话中就不再重复询问。在 macOS 上还可以进一步配置~/.ssh/config来使用系统钥匙串让重启电脑后也不用重新添加Host * AddKeysToAgent yes UseKeychain yes IdentityFile ~/.ssh/id_ed25519不过我仍然建议在关键设备上不要图方便把所有钥匙都交给系统保管。它确实很方便但也意味着一个设备失守所有权限就可能被拿走。安全意识不能丢。4.4 验证连接和远程地址切换密钥放好之后先验证一下连通性以 GitHub 为例ssh -T gitgithub.com首次连接会提示确认 host key输入 yes 确认即可。如果配置正确会看到一段欢迎信息指出你的用户名。这一步验证的意义是提前确认密钥有没有配置对而不用等到第一次 push 才发现问题。如果提示了 permission denied那就去排查是否公钥没贴对、私钥路径是否有问题。接着如果你是之前用了 HTTPS 远程地址的老仓库可以这样切换到 SSHgit remote set-url origin gitgithub.com:用户名/仓库名.git以后所有 push/pull/fetch 都不会再出现密码输入框了。5. 效率进阶配置别名和提交模板5.1 别名配置把你的高频命令缩成一个词Git 命令本身不算长但组合起来用就长了。比如你可能经常想看到单行浓缩的提交历史默认命令长这样git log --oneline --graph --all --decorate我配置了别名之后缩成一个单词git config --global alias.lg log --oneline --graph --all --decorate git config --global alias.st status -sb git config --global alias.br branch -vv配置完之后日常使用变成git lg git st git br关于别名这块网上有不少人喜欢把git checkout缩写成git cogit commit缩写成git ci这些看个人习惯就好。但是有一点我的体会极其深刻别为了追求缩写省那几个字符而配置出二义性别名。比如把git push别名为git p你敲习惯后发现再敲git pull容易手滑打成git pl那个手感真的是灾难级。所以别名的设计原则是短、直观、不易混淆。5.2 提交信息模板用规范约束团队习惯有些团队会把提交信息规范得很细比如要求带上需求单号、模块名。与其靠人肉记忆不如配置一个默认提交模板git config --global commit.template ~/.git-commit-template.txt模板文件内容可以是这样类型(范围): 简述 详细描述本次变更的原因和影响 相关需求单#有了这个模板每次执行git commit时编辑器里会自动带出这个结构引导你按规范写提交信息。提交信息规范的价值比你想象的大得多一个项目几万条提交记录如果都是“fix bug”“update code”这种没有营养的描述后续排查历史问题时基本抓瞎。但如果你用feat(login): 增加短信验证码登录这样的格式甚至可以直接用脚本从提交记录中自动生成变更日志这也是很多团队发布版本时 release notes 的来源。格式规范这件事强烈建议在项目开始的第一天就定下来。中途再改成本真的很高因为你得教所有人新写法外加推动历史沉淀非常痛苦。5.3 记住密码的全局安全策略有些场景下你不得不用 HTTPS 远程地址比如内网 GitLab 平台不支持 SSH。这种情况下避免每次输密码的方式是启用凭据缓存git config --global credential.helper store这个配置会把密码明文存在磁盘上方便是方便但安全性非常差。我更推荐另一种git config --global credential.helper cache --timeout3600这个配置的含义是密码只缓存一小时超过后需要重新输入。如果实际场景安全等级更高、或者机器是公用的那干脆连缓存都不开每次手动输入密码就好。我自己的策略是个人电脑上用 store团队公用电脑上用 cache仅此而已。一定要记得公共设备的 Git 凭据最忌讳用 store 模式。那种机器本来就人多手杂密码被人拷走你都不知道。5.4 文件和文件的忽略规则.gitignore 配置时机很多人忽略.gitignore文件想着反正就一点临时文件没必要管。但我经历过一次事故之后彻底改了这个习惯某次提交时不小心把包含数据库连接信息的.env文件推到了远端仓库虽然是私有仓库但还是吓出一身冷汗后来全力清历史、改密码步骤麻烦得让人想砸电脑。建议项目初始化时就直接写好.gitignore。GitHub 官方维护了一个.gitignore 模板仓库覆盖了各种语言和框架的通用忽略规则比如 Java 的target/、Python 的__pycache__/、Node 的node_modules/直接参考或者复制过来用即可。如果你发现已经有文件被追踪了就算.gitignore里面写了也拦不住这时候需要先从索引里移除git rm --cached 文件名这个过程没有写进全局配置里但它属于“配置 Git 习惯”的重要一环——在项目开始前把规则定好远好过一旦泄露之后的救火。6. 多仓库配置一份全局设置多把不同钥匙6.1 目录级别配置公司项目和私人项目隔离很多人会用同一台电脑同时处理公司项目和私人项目。这时候如果共用同一个全局身份信息出来的提交记录就会张冠李戴公司仓库里出现你的私人邮箱或者私人 GitHub 上挂着公司邮箱非常不专业。Git 提供了全局配置的 includeIf 特性可以实现“按目录匹配不同的配置文件”git config --global includeIf.gitdir:~/work/.path ~/.gitconfig-work git config --global includeIf.gitdir:~/personal/.path ~/.gitconfig-personal然后分别创建两个文件# ~/.gitconfig-work [user] name 张三-公司 email zhangsancompany.com# ~/.gitconfig-personal [user] name 张三 email zhangsanpersonal.com这个做法的思路是在~/work目录下创建或克隆的任何仓库都会自动应用公司的身份配置在~/personal目录下则是私人身份配置。我第一次用上这个功能时真的觉得相见恨晚之前我都是每次进到项目目录手动再执行一遍公司邮箱配置忘了就是事故。6.2 多 SSH Key 的 host 配置除了身份信息分开SSH Key 也应该按场景分开。比如公司 GitLab 用一把专用 Key私人 GitHub 用另一把。全部默认使用同一把的话相当于把所有鸡蛋放在同一个篮子里公司不让你呆了之后你私人代码权限就暴露了。具体做法是在~/.ssh/config文件里这样配置Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work配置完之后Git 根据远程地址自动挑选对应的私钥文件去认证不需要你手动指定。实测下来这一套配置在我重装电脑之后恢复环境的效率特别高——只要把~/.ssh和~/.gitconfig备份带走到新机器一恢复所有 Git 环境原地复活。7. 常见问题与排查技巧实录7.1 push 被拒Permission denied (publickey)这个错误提示几乎每个 SSH 配过的人都见过。排查步骤按这个顺序来就不会乱确认~/.ssh下存在公钥和私钥文件比如id_ed25519和id_ed25519.pub确认公钥内容已粘贴到托管平台的 SSH Keys 页面确认~/.ssh/config如果有的话里针对该 Host 的 IdentityFile 路径正确执行ssh -T gitgithub.com看报错细节大部分问题都出在第 2 步和第 3 步。尤其是复制公钥内容时中间不能多空格、不能少字符我见过有人复制时丢了末尾的几个字符导致验证失败折腾了一个多小时。7.2 提交信息编辑器里写不出来被 Vim 困住如果你没设置 core.editor默认是 Vim进入提交信息编辑界面后不知道怎么退出原地崩溃。解决办法很直白git config --global core.editor code --wait或者用 nanogit config --global core.editor nano顺带说一下如果已经在 Vim 里了想退出提交流程的话方法是先按Esc再输入:q!强制退出不保存这样提交就会被中止不会留下半拉子提交。这个操作熟练了之后你看到 Vim 界面就很淡定了不过我还是劝你直接把编辑器换了。7.3 中文乱码文件名和提交信息显示为转义字符执行git status时中文文件名显示成一串\346\265\213\350\257\225这基本就是没有设置core.quotepath false导致的。执行git config --global core.quotepath false配置全局生效之后重新打开终端或者重新执行命令中文显示就恢复正常了。这个配置挺冷门很多用 Git 一年多的同事都不知道但遇到一次就非常糟心。7.4 commit --amend 修改提交信息之后 push 冲突修改最近一次提交信息用git commit --amend但注意如果这个分支已经 push 到了远程且其他人已经把分支拉走了这时候你再git push大概率会被拒绝。原因是你把历史改了本地和远程的提交 SHA-1 对不上了。这种情况的处理要特别小心如果这个分支只有你一个人用且没有同事基于它开发那可以git push --force-with-lease强制推送如果多人共用建议不要直接强推而是创建新的提交修正或者走 PR 的方式--force-with-lease比--force安全得多它的含义是只有当远程分支的当前状态和你上次拉取的一致时才允许强制推送避免覆盖掉别人新增的提交。在团队协作里强推是不可逆的高风险操作我一般只有在清楚地知道只有自己动这个分支的情况下才敢用。7.5 全局配置写错了怎么改修改某个配置项直接重新执行一次 config 命令即可覆盖比如git config --global user.name 新名字如果想删除某个配置项用git config --global --unset user.name如果改乱了想整体重置直接编辑~/.gitconfig文件或者删掉它重新配置。在细拆之前一定要记住~/.gitconfig是你所有仓库的爸爸配置改错了所有使用全局配置的仓库都会受影响。操作前先cp ~/.gitconfig ~/.gitconfig.backup留个备份这是最稳妥的习惯。8. 备份和同步配置换电脑十分钟恢复环境配置好所有 Git 环境之后你以为就完了其实还有最后一步非常关键把配置备份下来这样换电脑、重装系统的时候不用重新摸索一遍。最简单粗暴的方案是把这几个文件打包cp ~/.gitconfig ~/.gitconfig-work ~/.gitconfig-personal ~/.ssh/ ~/git-config-backup/然后把这个备份目录传到自己的私有云盘或者加密压缩包里。~/.ssh里面包含私钥文件所以一定要加密压缩推荐用gpg或者zip加密方式。安全设置不能省。另外一个更进阶的同步方案把你的点文件比如.gitconfig、.ssh/config不含私钥放到一个 Git 私有仓库里维护。这样每次修改配置、提交一下同步到远端换电脑的时候直接 clone 下来就还原了大部分环境。私钥单独备份到安全硬件或加密容器中不要提交进仓库。我自己摸索出来的习惯是配置完一套 Git 环境后花两分钟写个简单的备份脚本内容就是打包copy那几份文件执行一次心里踏实。宁可脚本多余也不要到了急需环境的时候抓瞎。很多人重装系统之后或多或少都经历过找各种配置文件的痛苦提前备份真的能避免大半烦恼。最后再说一点体会吧。Git 的配置它不是一次性工作它是你在实际使用中不断微调的。今天觉得这个别名顺手明天觉得那个工具更好都是正常的。关键是你要懂得配置背后的含义——配置存放的位置、优先级、不同协议的工作方式而不仅仅是背命令。把这些基础打牢了后面碰到任何奇怪的 Git 问题你排查起来就不会像无头苍蝇一样乱撞。想让你帮忙给我通过这个方案增强用户体验的行链接 // 基于项目的操作只有项目自己有权利... 的这句话是怎么实现的帮我技术剖析下这个文章技术细节 用git如何把本地项目推到github上 git具体方法