每隔一段时间就会有人来问我同一个问题在Windows上装Git到底怎么才算装明白别看网上一搜全是Git下载安装教程真按那些教程点完下一步十个人里至少有一半会在后面的环境配置和SSH密钥环节卡住。git命令不识别、换行符捣乱、每次推送都要输密码、Permission denied报错查不到原因——这些我都经历过也帮别人排查过无数次。这篇文章不玩虚的从Git下载、安装、环境配置到SSH密钥免密推送把每一步的选项、原理、坑位一次讲清楚。无论你是刚接触版本控制的新人还是在VS Code、Vue3、Node.js、Java等工程里已经把Git当日常工具的开发者这篇都值得你完整过一遍。1. 写在动手之前为什么Windows装Git总比别人多一道坎1.1 Git解决什么问题先搞清楚再动手Git是目前使用最广泛的分布式版本控制系统由Linux之父Linus Torvalds在2005年开发最初是为了维护Linux内核代码。它的核心价值可以浓缩成三句话记录文件的每一次改动、支持多人并行协作、出了问题可以随时回退到任意版本。很多人误以为Git是程序员的专属工具其实不是。做文档管理、写博客、维护配置脚本、管理设计稿的工程文件Git都适用。尤其是当你配合GitHub、Gitee这类远程托管平台使用时代码在云端有一个备份换电脑、同事协作、历史版本回溯都变得非常简单。在当前的开发环境中Git已经和编译器、编辑器一样属于装了不一定马上用到但不装一定会卡住的基础设施。在Windows上装Git环境配置永远比安装本身更值得花时间研究。这是因为Windows不像Linux和macOS那样自带或半自带Git所有东西都要自己手动弄而且Windows的路径体系、换行符规则、终端环境都和Unix系系统不一样这些差异会在后续使用中持续制造麻烦。提前理解这些差异能帮你省下后面大量的排查时间。1.2 动手前的三项自查系统位数、权限、现有Git安装之前先花两分钟做三项自查避免装到一半才发现环境不匹配。第一确认Windows系统版本和位数。在运行框WinR里输入winver回车会弹出版本信息窗口。绝大多数现代电脑都是64位系统Git官方也提供了64位、32位和ARM64三种Windows安装包选对应版本就行。32位系统现在已经很少见如果你还在用建议优先解决系统问题而不是执着于Git版本。第二确认当前用户是否具备管理员权限。Git默认安装到C:\Program Files\Git这个目录受系统保护普通权限可能写不进去。如果你在会议室临时拿了一台公司电脑又不想找管理员要密码可以考虑用后面要讲的Portable便携版它不需要写系统目录。第三检查电脑上是不是已经有一个看不见的Git。很多软件会静默捆绑Git作为内置组件比如一些IDE、Node.js工具链、自动化脚本工具。在CMD或PowerShell里执行git --version如果返回了版本号说明电脑上已经有Git了这时候要考虑是直接使用现有版本还是卸载重装一个干净的新版本。多个Git并存不是不行但PATH环境变量里谁先谁后会导致命令解析到不同版本排查起来非常头疼我一般建议只保留一个官方最新版。1.3 三种安装方式怎么选官方安装包、winget、PortableWindows装Git主要有三条路我按推荐程度给你排个序。首选官方安装包Git for Windows Setup去https://git-scm.com/downloads下载优点是安装向导可以自己控制每一个选项后面我会逐个讲解哪些勾、哪些不勾。这也是本文主要讲解的方式。其次是用Windows包管理器winget命令一行搞定winget install --id Git.Git -e --source winget这个方式适合追求效率的老手装完之后也能正常使用。但它默认按官方推荐选项安装你没法在过程中微调比如默认编辑器、PATH模式这些。如果你对Git还不太熟我更建议你老老实实走一遍官方安装向导因为你得知道自己到底装了什么。最后是Portable便携版下载后解压就能用不需要安装也不会改动系统环境变量。适合U盘里随身携带环境、或者电脑权限受限的场景。但要注意便携版默认不会自动写入PATHgit命令在普通终端里可能找不到每次都得进到解压目录里用或者手动配一次环境变量这一点不建议新手尝试。2. 从下载到安装向导每个选项背后的取舍逻辑2.1 官网下载与版本选择别被最新版绑架打开https://git-scm.com/downloads点Windows会进入下载页面页面上会列出当前最新的64-bit setup、32-bit setup和Portable版本。版本号大概长这样2.4x.x比如2.47.x、2.48.x。我的建议是版本号不用过度追求最新但也不要落后太多。Git的版本迭代很快新版本主要带来性能优化、新命令和Bug修复。你只要下载官网首页展示的那个版本就行通常就是最新的稳定版。页面下方还有Git for Windows的完整Release列表没有特殊需求不用翻那个列表挑最新的点下载就好。下载后你会得到一个名字类似Git-2.48.1-64-bit.exe的安装文件右键以管理员身份运行。接下来弹出的安装向导才是真正决定这台机器的Git好不好用的地方。2.2 安装向导逐项拆解七个关键界面别乱点整个安装向导大概有十几步大部分直接Next就行但下面这几个界面必须认真看。第一个要留意的是Select Components选择组件。默认选项里有两项建议保持勾选Git Bash Here和Git GUI Here这是右键菜单集成让你在资源管理器里右键就能打开Git Bash终端日常效率提升非常大。Git LFS (Large File Support)大文件支持处理超过100MB的文件时用得上建议勾上以后要用不用重新装。至于Associate .git configuration files with default editor将.git配置文件关联到默认编辑器和Associate .sh files to be run with Bash让.sh脚本用Bash运行保持默认即可。这两个选项影响的是文件双击打开方式不勾也不影响命令行使用。第二个关键界面是Select the default editor used by Git选择默认编辑器。这里默认是Vim很多新手在git commit时误入Vim界面进去之后不会保存退出只能强制关窗口非常崩溃。如果电脑上装了VS Code强烈建议选Use Visual Studio Code as Gits default editor如果没装选Use Nano也比Vim友好很多。我自己在生产环境里会用Vim那是为了效率但新手阶段没必要和自己较劲。这个选择以后也可以改命令是git config --global core.editor code --wait第三个关键界面是Adjusting your PATH environment调整PATH环境变量这是全安装过程中最最重要的一步。三个选项分别为选项含义推荐度Only use Git from Git Bash只在Git Bash里用git不推荐Git from the command line and also from 3rd-party software在CMD、PowerShell、Git Bash和其他第三方软件中都能用git强烈推荐Use Git and optional Unix tools from the Command Prompt把Git自带的大量Unix工具也装进PATH不推荐新手选选第一个的话你在CMD或者VS Code的终端里输入git会提示找不到命令对日常开发影响极大。选第三个则会让Git自带的find、sort等Unix工具覆盖Windows内置同名命令可能引发脚本行为异常。中间那个选项是最平衡的既能让IDE识别Git又不会干扰系统原有命令。2.3 HTTPS后端、换行符、终端模拟器三个容易被忽略的坑继续往下走还有三个选项我单独拎出来讲因为它们会在你日后的使用中制造大量莫名其妙的问题。HTTPS transport backendHTTPS传输后端默认是Use the OpenSSL library这是标准选择和GitHub、Gitee、GitLab这些平台都能良好兼容。另一个选项Use the native Windows Secure Channel library用的是Windows证书存储机制适合企业内部使用自签名证书的场景。除非你所在的公司有明确要求否则别动保持OpenSSL。Line ending conversions换行符转换默认选项是Checkout Windows-style, commit Unix-style line endings对应的配置是core.autocrlftrue。这里说说为什么。Windows用CRLF回车换行作为换行符而Linux和macOS用LF仅换行。如果同一份代码在不同系统之间来回切换而不做转换会出现Git提示整个文件都发生变化的假象。默认选项会在检出代码时把LF转成CRLF提交时再转回LF保证仓库里存的始终是Unix风格。对于绝大多数Windows用户保持默认就是最省心的方案。但这里有一个团队协作的细节如果你的团队里有人用macOS或Linux而你在Windows上改文件只要大家都保持Git默认配置仓库里存储的格式就是统一的不会出问题。真正出问题的是有人手动改了core.autocrlf或者用某些编辑器做了智能换行处理。这点我在后面踩坑实录里详细讲。Terminal emulator终端模拟器默认是Use MinTTY另一个选项是Use Windows default console window。MinTTY提供了更丰富的终端功能比如CtrlShiftC/V复制粘贴、窗口大小自由调整、鼠标选中复制等这是我平时在Windows下用Git Bash的主力终端。但它的复制粘贴快捷键和Windows传统习惯不太一样新手容易产生怎么复制不了的困惑。Windows TerminalWindows 11自带的终端已经非常成熟如果你习惯它也可以在向导里选Windows默认控制台然后在Windows Terminal里把Git Bash注册成其中一个Profile体验同样不错。这个选项不用太纠结后期随时能改。2.4 收尾选项pull策略、凭据管理器、符号链接后面的界面里git pull的默认行为保持Default (fast-forward or merge)即可。这表示git pull时默认用merge方式合并远程更新对新手来说最直观、最容易理解。Rebase方式的历史更线性但容易产生冲突处理上的心智负担不建议初始就这样设置。Credential Manager凭据管理器一定要保持默认的Git Credential Manager。它的作用是以后你用HTTPS方式克隆私有仓库时第一次会让你登录授权之后会把令牌保存在Windows凭据管理器里不用反复输入密码。虽然我们后面主要用SSH密钥但HTTPS方式作为备用通道也很有价值。最后的Extra options里Enable file system caching保持勾选它能显著提升Git在大仓库下的文件操作性能。Enable symbolic links建议不勾Windows下创建符号链接需要开发者模式和管理员权限勾上反而容易引出权限类的报错。一切设置完成后点击Install开始安装等到进度条走完出现Finishing界面时记得先取消勾选View ReleaseNotes再点Finish不然会弹出一个浏览器窗口没什么实际用处。到这里安装环节就结束了。3. 环境配置验证安装、配置身份与值得设置的全局项3.1 用三种终端验证安装是否成功安装完成后打开一个新的CMD窗口、PowerShell窗口或Git Bash窗口。注意一定是新窗口因为安装程序修改的PATH环境变量只在新的进程里生效旧窗口还保留着旧环境。然后执行git --version能返回类似git version 2.48.1.windows.1的结果说明安装成功。如果提示git 不是内部或外部命令说明PATH配置出了问题具体排查方式我在踩坑实录里展开。在Git Bash里还可以顺手看一眼Git的安装信息echo $SHELL which gitwhich git会输出git的可执行文件路径正常情况应该是/cmd/git或/mingw64/bin/git一类的路径。这一步能帮你确认当前用的是哪个Git避免多个版本混乱。3.2 配置user.name和user.email提交记录的身份证Git安装完毕后的第一件事是告诉它你是谁。这个身份信息会写进每一次提交记录别人通过git log看到的就是这个作者信息。git config --global user.name Your Name git config --global user.email youexample.com把引号里的内容换成你自己的名字和邮箱。邮箱建议使用你注册GitHub或Gitee用的那个邮箱这样你的提交能在平台主页上正确关联到你的账号否则会被识别成未关联作者的孤立提交。这里需要理解Git配置的三层作用域很多奇怪的为什么我改了配置没生效问题都出在作用域上。Git配置从高到低分为作用域配置文件位置生效范围命令系统级C:\Program Files\Git\etc\gitconfig当前电脑所有用户git config --system全局级C:\Users\你的用户名\.gitconfig当前用户所有仓库git config --global仓库级.git\config当前仓库git config --local配置读取规则是从系统到仓库逐层覆盖也就是仓库级配置优先级最高。如果你在某个仓库里发现git作者信息不对第一件事就是执行git config --local --list检查是否有仓库级配置覆盖了全局设置。修改完可以执行git config --list --show-origin这个命令会把所有生效的配置项及其来源文件一起列出来一目了然排查问题时非常好用。3.3 几个我强烈建议顺手配置的全局项下面几项是我每次给新环境配Git都会顺手敲进去的全局配置它们能避免很多后续使用中的小麻烦。# 1. 新仓库默认分支名设为main git config --global init.defaultBranch main # 2. 让git status等命令正确显示中文文件名 git config --global core.quotepath false # 3. 明确git pull默认使用merge策略 git config --global pull.rebase false第一条原因很简单GitHub、Gitee新建仓库默认分支都是main但本地git init出来的仓库默认还是master两边不一致后面push时老是要处理分支重命名问题。提前设为main从源头消除差异。第二条core.quotepath false解决的是中文显示问题。Git默认会把非ASCII字符转义成八进制编码比如中文文件名需求文档.md在git status里显示成\350\257\257...一串乱码正常人根本看不懂。设成false之后中文就能正常显示了。第三条pull.rebase false和安装向导里的pull策略是一致的如果安装向导选了默认这条可以不敲但写上更保险防止某些工具或后续操作把策略改掉。如果你用HTTPS方式比较多可以顺手确认一下凭据助手配置git config --global credential.helper manager这行配置配合安装向导里的Git Credential Manager能让你在Windows上第一次HTTPS推送时自动弹出授权窗口后续免密。虽然SSH密钥才是主流但HTTPS作为备胎通道一直很稳。4. SSH密钥从生成到免密推送的完整闭环4.1 为什么我推荐SSH而不是HTTPSGit连接远程仓库有两种主流协议HTTPS和SSH。HTTPS的优点是门槛低克隆仓库时直接填地址就能用。但现在GitHub已经不再支持纯密码认证必须使用个人访问令牌Personal Access Token每次还得在网页上生成、复制、粘贴令牌还会过期过期之后又要重新来一遍体验确实说不上好。SSH密钥的方式则是一劳永逸本地生成一对密钥私钥公钥把公钥添加到GitHub或Gitee账号里之后这台电脑的所有推送和拉取都不需要再输任何密码和令牌。密钥对的安全模型也很清晰公钥随便公开私钥永远保存在本地~/.ssh目录下只要私钥不泄露身份就是安全的。对于天天要跟代码仓库打交道的开发者SSH是效率最高、最省心的选择。4.2 生成密钥前的检查与ssh-keygen实操打开Git Bash先看看~/.ssh目录下是否已经有密钥ls -la ~/.ssh如果已经有id_ed25519或id_rsa这类文件说明以前生成过可以直接复用不用再生成。如果使用的是别人的电脑或者密钥不确定安全建议删除旧密钥或指定新文件名重新生成避免误用。确认干净之后执行ssh-keygen -t ed25519 -C youexample.com这里解释一下参数-t ed25519指定密钥类型。Ed25519是目前推荐的现代算法密钥短、生成快、安全性高。如果你的Git服务器系统比较老不支持Ed25519可以改用-t rsa -b 4096生成RSA 4096位密钥。-C youexample.com给密钥加一个注释通常是你的邮箱方便在服务器端识别这把钥匙是谁的。执行后Git Bash会询问保存位置Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):直接回车使用默认路径即可。接着会提示输入passphrase口令Enter passphrase (empty for no passphrase): Enter same passphrase again:这里我建议设置一个口令。有人觉得每次用密钥都要输口令很烦想留空图省事。但一旦私钥泄露比如U盘丢失、电脑被盗没有口令保护的私钥等于白送。设置口令之后配合ssh-agent只输一次就可以实际负担并不大。生成成功的提示大概长这样Your identification has been saved in /c/Users/你的用户名/.ssh/id_ed25519 Your public key has been saved in /c/Users/你的用户名/.ssh/id_ed25519.pubid_ed25519是私钥绝不能外传id_ed25519.pub是公钥可以放心交给任何Git平台。查看公钥内容的命令是cat ~/.ssh/id_ed25519.pub也可以用一条命令直接把公钥内容复制到Windows剪贴板省去手动选中的麻烦clip ~/.ssh/id_ed25519.pub4.3 把公钥交到GitHub、Gitee和GitLab复制好公钥之后去对应的代码托管平台添加。以GitHub为例登录后在右上角头像 → Settings → 左侧菜单找SSH and GPG keys→ 点New SSH key在Title里填一个能认出来的名字比如Windows办公电脑在Key文本框里粘贴刚才复制的公钥然后点Add SSH key。Gitee的操作路径是登录后点右上角头像 → 设置 → 左侧安全设置→SSH公钥→ 把公钥粘进去添加即可。GitLab则是登录后点头像 → Preferences偏好设置 → 左侧SSH Keys→ 粘公钥 → Add key。这里有个容易踩的坑添加时不要把公钥内容改坏。公钥是一整行字符串以ssh-ed25519 AAAA...或ssh-rsa AAAA...开头以注释邮箱结尾。有些人复制到网页时文本被换行拆成多段粘贴后平台会提示格式错误。稳妥的做法是粘贴后检查开头结尾确保是一行完整内容。4.4 验证连接与多平台多账号配置添加完公钥回到Git Bash验证连接ssh -T gitgithub.com第一次连接会弹出确认提示The authenticity of host github.com (20.205.243.166) cant be established. Are you sure you want to continue connecting (yes/no/[fingerprint])?输入yes回车这个提示是正常的说明你的SSH客户端在确认目标主机的指纹输入yes之后会把它写进known_hosts文件以后再连就不会问了。验证成功的输出是Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.看到这句就说明SSH密钥配置完毕。Gitee的验证命令是ssh -T gitgitee.com成功会返回欢迎信息。如果你同时使用GitHub和Gitee又不想让两个平台都使用同一把钥匙可以在~/.ssh目录下新建一个config文件配置不同平台走不同密钥。比如# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github # Gitee Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee这样SSH连接时会根据Host自动选择对应的私钥文件一套配置管多个平台互不干扰。我自己就是这么干的GitHub一把钥匙Gitee一把钥匙私钥口令不同风险隔离。配置完成后为现有仓库切换远程地址git remote -v如果远程地址是https://github.com/用户名/仓库名.git换成SSH形式git remote set-url origin gitgithub.com:用户名/仓库名.git然后再执行git push全程不需要输入任何密码才算真正配好了。5. 踩坑实录安装与SSH配置中最常见的五个翻车点5.1 git不是内部或外部命令先别重装检查这里这个报错九成以上出现在三种情况安装时PATH选错了、装完没开新终端、用了Portable便携版。排查链路很简单。第一步在CMD里执行where git如果返回路径说明Git其实装好了只是当前终端的环境变量过期关掉重开一个新终端就行。如果提示找不到说明PATH里根本没有Git目录。第二步手动确认安装目录下的cmd目录是否存在。默认路径是C:\Program Files\Git\cmd里面应该有git.exe。如果这里没有说明安装位置不对或安装不完整。第三步手动把目录加进PATH。在Windows设置里搜索编辑系统环境变量 → 环境变量 → 在Path变量中添加C:\Program Files\Git\cmd和C:\Program Files\Git\bin保存后重开终端。这里多说一句cmd目录和bin目录里的git.exe功能上有差异。cmd里的git.exe是一个轻量包装器主要供CMD和第三方程序调用行为更接近Windows原生程序bin里的git.exe是完整的Git二进制文件。IDE集成一般指向cmd\git.exe命令行使用两个都能跑PATH里把cmd放前面即可。5.2 Permission denied (publickey)的完整排查链路SSH连不上远程仓库时最常见的报错是gitgithub.com: Permission denied (publickey).这个错误信息很笼统背后可能是五六个原因。我现在遇到这个问题会按下面的顺序排查你跟着走一遍基本能定位。第一步用详细模式看SSH到底尝试了哪些密钥ssh -T gitgithub.com -v执行后观察输出。重点看Offering public key这一行确认SSH是否使用了你期望的那把私钥。如果输出的密钥文件和你希望的不一样说明~/.ssh/config或默认文件名配置有问题。第二步检查远程地址是不是HTTPS。执行git remote -v如果显示的是https://github.com/...那不管SSH密钥配得多完美都不会生效。解决办法是用git remote set-url origin gitgithub.com:用户名/仓库名.git切换协议。第三步确认密钥是否被ssh-agent加载ssh-add -l如果输出的指纹和你生成的密钥不一致或者提示The agent has no identities就手动加载eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519第四步确认公钥有没有被正确添加到对应的平台和账号。这里有一个高频翻车点同一台电脑上有多个账号公钥添加到了A账号但仓库是从B账号克隆的当然会被拒绝。还有的公司内部GitLab限制了SSH密钥的回源IP换了网络环境才暴露问题。第五步检查私钥文件权限。Windows下私钥文件权限过宽会导致SSH拒绝使用它。右键私钥文件 → 属性 → 安全 → 确认只有当前用户有完全控制权限。如果你是从旧电脑把.ssh目录整个拷过来的权限记录很可能乱了这一步尤其重要。5.3 CRLF和LF的换行符之争为什么整个文件都被修改这是Windows用户独有的痛。症状是明明只改了一行代码git diff却显示整个文件都被标记为修改或者提交时反复提示warning: LF will be replaced by CRLF。根因是换行符不一致。前文说过Windows仓库标准是core.autocrlftrue检出时转CRLF、提交时转LF。但如果仓库里已经混入了纯LF历史文件或者有人在编辑器里强制改了换行格式Git的自动转换就会失灵。我处理这类问题的顺序是先看仓库自己的换行策略配置打开仓库根目录下.gitattributes文件如果没有就新建一个。在.gitattributes里显式声明文件类型和换行规则比如* textauto *.md text eollf *.bat text eolcrlf *.png binary这个文件的作用是让Git按照声明规则处理换行不依赖每个人本地配置。团队协作时只要这个文件提交进仓库大家统一遵守换行符问题就基本绝迹了。这比让每个人手动改core.autocrlf靠谱得多。另外如果老仓库已经出现了大量换行符混乱的历史记录可以用git add --renormalize .把现有文件重新按规则规范化一次提交一个换行符合规的变更。5.4 中文乱码与文件名显示问题Windows下使用Git中文乱码有两种常见情况。第一种是命令行输出乱码比如git log里的提交信息显示成锟斤拷之类的符号。解决方案是把Git Bash终端编码设为UTF-8。如果你用的是Windows Terminal默认就是UTF-8基本不会遇到这个现象。如果是老版CMD需要在窗口标题栏右键 → 属性 → 选项里把代码页设为UTF-8 (65001)。第二种是中文文件名被转义git status显示的不是需求文档.md而是一串\350\257\267。这个在前面已经提过执行git config --global core.quotepath false就能解决。顺带建议把这两行也配上git config --global i18n.commit.encoding utf-8 git config --global i18n.logoutputencoding utf-8这样提交信息里写中文日志输出中文都能正常显示。5.5 办公网络下SSH连接卡住或超时有时你会在公司网络或某些受限网络环境下发现ssh -T gitgithub.com执行后半天没反应最后报超时。这通常是网络环境屏蔽了SSH默认的22端口。我遇到这种情况首先会确认本机是否真的无法访问22端口。可以在Git Bash里用ssh -T gitgithub.com -p 443试试GitHub官方提供了一条TSL方式的SSH over 443通道专门用来应对22端口被封锁的场景。配置方法是在~/.ssh/config里加一段Host github.com HostName ssh.github.com Port 443 User git然后重新执行ssh -T gitgithub.com验证通常就能连上。这个方案只影响SSH连接方式不影响其他网络访问属于官方支持的标准做法。如果公司内网用的GitLab、Gitee等私有部署平台也出现类似情况那就是另一套排查方案了——重点看公司是否要求走内部代理或特定端口这个因环境而异最直接的办法是问你们运维要一份SSH连接规范。我在实际配置过上百次Git环境之后最大的体会是安装本身五分钟就能搞定真正区分会用和不会用的是你能不能把换行符、路径、密钥这三件事的原理讲清楚。每次有人带着报错截图来找我十次里有八次问题都出在PATH和SSH密钥两件事上。上面这五类坑覆盖了我在Windows上遇到过的绝大多数问题你把这篇文章存下来遇到对应报错直接翻到对应小节大概率能省下一下午的折腾时间。