1. 先搞清楚Windows配Git最容易踩的五个坑Windows上配Git说难不难说简单也真的不简单。这两年我帮同事和朋友装过不下二十台Windows机器的开发环境几乎每次都会在同一个地方多花十几分钟——不是下载安装包而是装完之后各种小问题接踵而至命令行找不到git、提交中文路径乱码、每次push都要输密码、SSH连不上远程仓库……这些坑单独看都不大串在一起就特别磨人。所以这篇就按“下载—安装—环境配置—SSH密钥”这条线把Windows下Git从零到能正常提交代码的完整过程走一遍。内容主要适合三类人刚接触Git的纯新手、换了新电脑需要从头配环境的开发者以及给团队写内部文档的技术负责人。不管你是用GitHub、GitLab还是公司自建的代码服务器这套流程基本都能覆盖。先说结论在Windows上配Git核心不是“把安装包点完”而是装完之后的三个动作——配好PATH、配好全局参数、配好SSH认证。这三件事都做完Git才算真正在Windows里“落地”了。1.1 最大的坑其实是“装完不会用”很多教程到安装完成就收工了但恰恰是安装之后的配置环节才是大多数人卡住的地方。我见过不少同事Git装好了VS Code里插件也装了但一提交就报“Please tell me who you are”或者每次clone都要输账号密码又或者命令行里敲git直接就“不是内部或外部命令”。这些问题都不是Git本身坏了而是环境配置没跟上。Windows和Linux最大的区别在于Linux发行版通常自带Git或者包管理器帮你把依赖都处理好而Windows上Git更像一个“外来客”装完之后还需要手动把它接入系统环境和Shell体系。再加上Windows默认的命令行工具、换行符规则、编码规则和Unix生态都不一样配置的时候少注意一个细节后面就是一连串的坑。1.2 为什么推荐“标准三步走”流程这套流程我命名为“下载安装—基础配置—SSH认证”顺序不能乱。先把安装包装好、PATH配好保证git命令在终端里能用接着配置用户身份、换行符、编码这些全局参数保证第一次提交不报错最后再生成SSH密钥并登记到代码平台保证push和pull不再输入密码。为什么SSH要放在最后因为SSH的验证过程会读取本地git配置和系统用户目录如果前面基础配置没做好ssh -T命令返回的错误信息会混入很多干扰项新手很难判断是密钥问题还是路径问题。先把地基打好后面排查起来就清爽很多。2. 保姆级下载与安装安装选项逐个给你说清楚2.1 去哪下载最靠谱Git官方下载地址是git-scm.com/download/win进入页面后会自动检测Windows系统一般推荐下载64-bit的Standalone Installer版本。这个版本是官方编译的完整安装包功能最全更新也最及时。如果在国内访问官网下载速度不理想可以用清华、阿里或华为的开源镜像站。这些镜像站会同步Git官方发行版文件名和校验值和官网一致下载完建议对比一下SHA-256值确认安装包完整再用。另外我不建议用第三方“绿色版”“精简版”Git因为你不知道对方裁剪了哪些组件而这些组件往往就是后面环境变量和SSH出问题的根源。2.2 安装选项逐个过一遍Git安装包一路Next确实能装完但有几个选项如果选错后面要返工。我把关键选项整理成一份表格大家可以对着选。安装选项建议选择原因Additional icons按个人喜好对命令行工具影响不大Windows Explorer integration勾选在文件夹右键菜单加入Git Bash Here日常操作非常方便Git LFS (Large File Support)勾选仓库里有设计稿、模型文件时有大用装完一劳永逸Associate .git configuration files勾选双击配置文件能用默认编辑器打开排查问题更直观Associate .sh files看需求如果常用shell脚本建议关联纯开发环境可不勾Use a Git Bash only / Git from command line / Git from command line and 3rd-party software选第三项让Git同时接入cmd、PowerShell和VS Code等第三方软件避免以后IDE里找不到gitUse bundled OpenSSH / Use external OpenSSH选bundledGit自带的OpenSSH与Git版本配套减少兼容性问题Checkout Windows-style / Checkout as-is / Checkout Unix-style选第一项默认换行符自动转换对Windows和跨平台合作最友好Use MinTTY / Windows default console选MinTTY终端体验更好支持颜色和快捷键操作感接近Linux终端git pull默认行为选默认merge对新手友好操作最直观Credential Manager勾选配合Windows凭据管理器保存HTTPS密码省去重复输入Symbolic links不勾选Windows上符号链接需要管理员权限普通开发场景用不上选完这些选项安装过程剩下就是等待。装完之后先别急着用还有两个收尾动作要做一是检查“C:\Program Files\Git\cmd”是否已经写进系统的PATH环境变量二是重启一下终端窗口或干脆重启一次电脑确保环境变量生效。2.3 安装后的环境变量验证装完Git后的第一件事是打开Git Bash开始菜单里搜Git Bash输入以下三条命令验证安装结果git --version git config --list which gitgit --version能显示版本号说明Git主程序可用git config --list能显示默认配置说明配置文件读取正常which git能看到git可执行文件的具体路径一般会指向“/usr/bin/git”这是Git Bash自带的路径。如果打开cmd或PowerShell输入git提示“不是内部或外部命令”说明PATH没有配好。解决办法是右键“此电脑”→“属性”→“高级系统设置”→“环境变量”在系统变量Path里手动添加“C:\Program Files\Git\cmd”和“C:\Program Files\Git\bin”然后重新打开终端。这一步相当于把Git“介绍”给了整个Windows系统VS Code、JetBrains这些IDE的终端里也就自然能调用git了。3. 环境配置让Git在Windows里真正“好用”3.1 提交者身份和默认分支先设好Git安装完成后第一次提交前必须设置user.name和user.email。这个信息会写进每一次提交记录里相当于你的“签名”。不设置的话Git会直接拒绝提交并报“Please tell me who you are”。git config --global user.name 你的名字 git config --global user.email 你的邮箱 git config --global init.defaultBranch main为什么强调全局配置因为--global的意思是“这台机器上所有仓库都默认用这个身份”。对于大多数个人电脑开发场景这个设置是最省事的。如果你要在一个仓库里用不同身份可以删除--global在该仓库目录下单独执行git config user.name/user.email这样局部配置会覆盖全局配置。init.defaultBranch main是我特别建议加的一条。早年间Git默认分支名是master后来业界普遍转向main提前在全局设置里定好每次git init出来的仓库分支都是一致的不至于有的仓库是master、有的是main自己看晕了。3.2 换行符与中文乱码关键三件套Windows和Linux的换行符标准不一样Windows用CRLFLinux和macOS用LF。如果不做任何处理两个系统协作时会出现大量“整个文件都被改动”的假象明明只改了一行diff里却满屏飘红。解决这个问题的关键是core.autocrlf。git config --global core.autocrlf true git config --global core.quotepath falsecore.autocrlf true的意思是提交时自动把CRLF转成LF检出时自动把LF转成CRLF。这样Windows本地文件保持Windows习惯Git仓库里统一存LF跨平台协作时diff就干净了。如果你确定团队只在一个平台上开发可以设成false或input但绝大多数情况下用true是最稳妥的选择。第二条core.quotepath false是解决中文文件名和中文路径显示问题。Git默认会把中文路径转义成八进制字符比如把“文档”显示成“\346\226\207\346\241\243”加上这条配置之后终端里就能直接看到正常的中文文件名了。另外如果Git Bash里中文乱码可以顺手在系统环境变量里加一个LANGzh_CN.UTF-8再配合Windows Terminal使用UTF-8编码基本能根治乱码问题。3.3 常用辅助配置别名、默认编辑器、凭据缓存配置完上面这些日常使用还有一些小优化可以做。我给团队写的文档里经常推荐下面几条git config --global core.editor code --wait git config --global alias.lg log --oneline --graph --all --decorate git config --global alias.co checkout git config --global alias.br branch git config --global credential.helper managercore.editor设置为VS Code后git commit时如果不写-m参数会直接打开VS Code编辑提交信息比卡在vim里按半天Esc舒服太多。alias.lg是我最常用的一个别名一条命令就能看到整个分支的图形化提交历史。credential.helper manager则对接Windows凭据管理器走HTTPS协议时输过一次账号密码后后续会被系统缓存省去重复输入的麻烦。这里提醒一句credential.helper只有HTTPS协议才会启用如果你用SSH方式连接密码验证根本不走这一套所以SSH密钥配置依然是今天教程的重点。另外还有一种情况是多人共用一台电脑就不要再设--global了尽量用局部配置避免身份信息混淆。4. 从头到尾配好SSH密钥生成、登记、验证全流程4.1 为什么推荐SSH而不是HTTPSGit连接远程仓库有两种常见协议HTTPS和SSH。HTTPS配置简单第一次输入账号密码就行配合凭据管理器也能免密但很多代码平台已经不再支持纯密码认证必须用Personal Access Token那个token长不说过期了又要重新生成非常折腾。SSH则完全不同。它用一对密钥来做身份验证私钥留在本地公钥登记到代码平台。push和pull的时候Git用私钥签名平台用公钥验签整个过程不需要输入密码也不用管token什么时候过期。安全性上密钥对也比密码高得多私钥本身还可以再加一道口令保护。对于每天几十次push的开发场景SSH是效率和安全平衡得最好的方案。4.2 生成密钥ed25519还是RSA打开Git Bash执行下面这条命令生成SSH密钥ssh-keygen -t ed25519 -C 你的邮箱-t ed25519指定密钥算法。ed25519是当前推荐的新算法密钥短、生成快、安全性高GitHub和GitLab都已经支持。如果你的代码平台或者自建服务器比较老用ssh-keygen -t rsa -b 4096生成RSA密钥更稳妥RSA的兼容性最好几乎不会出问题。回车后命令行会询问密钥保存位置默认是~/.ssh/id_ed25519直接回车就行。接着会让你设置passphrase也就是私钥的口令。我个人的建议是电脑只有自己用、且安全环境相对可控的情况下可以不设如果是笔记本、经常出入公共场所最好设一个复杂点的口令。设了口令之后配合后面的ssh-agent每次开机只需要输一次口令平时使用依然是无感的。生成结束后用cat ~/.ssh/id_ed25519.pub查看公钥内容选中整段复制。注意.pub后缀的才是公钥可以给别人看不带后缀的id_ed25519是私钥打死都不要发给任何人一旦泄露对方就能冒充你操作代码库。4.3 启动ssh-agent并添加私钥如果你在生成密钥时设置了passphrase就必须借助ssh-agent把密钥加载到内存中才能做到“一次输入后续免密”。Windows上ssh-agent默认不是开机自启状态可以通过以下命令手动启动eval ssh-agent -s ssh-add ~/.ssh/id_ed25519第一条命令会让ssh-agent以后台进程方式运行第二条命令把私钥加入agent输入passphrase后就加载成功了。想验证的话执行ssh-add -l能看到已经加载的密钥指纹就说明成功了。如果希望ssh-agent开机自动运行可以在Windows服务管理器里找到“OpenSSH Authentication Agent”把启动类型改为“自动”然后启动服务。这样每次开机后打开Git Bash私钥自动加载不用重复输入passphrase体验很流畅。4.4 把公钥登记到GitHub或GitLab复制好公钥内容后登录GitHub进入Settings → SSH and GPG keys → New SSH key。Title随便填一个能识别设备的名称比如“Windows-Laptop-2026”Key区域粘贴公钥点Add SSH key就能完成登记。GitLab的操作路径类似在Preferences → SSH Keys里操作。登记完成后执行验证命令ssh -T gitgithub.com如果是GitLab自建服务器验证命令是ssh -T gitgitlab.你的域名.com具体以平台文档为准。第一次连接时终端会提示确认主机指纹fingerprint输入yes回车即可。如果能看到“Hi 用户名! Youve successfully authenticated”这行字说明SSH密钥已经生效可以正常通过SSH协议clone和push了。4.5 多账号与密钥文件管理很多人的实际场景是GitHub一个账号、公司GitLab一个账号甚至还有客户给的内网代码服务器。这种情况下如果只用一个默认密钥会出现A平台能用、B平台报Permission denied的尴尬。解决办法是用~/.ssh/config文件做多主机区分。在~/.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_gitlab生成密钥时建议用ssh-keygen -f ~/.ssh/id_ed25519_github这样指定文件名不同平台用不同密钥文件再通过config把Host和密钥文件对应起来。这样Git在连接不同域名时会自动读取对应的密钥再也不用反复增删密钥去试。改完config后执行一次ssh -T gitgithub.com和ssh -T gitgitlab.company.com两边都能打印出认证成功就说明多账号配置大功告成。5. 常见问题排查照表格对号入座就行5.1 报错信息速查表Windows上配Git来来去去就那么几个问题我把这些年遇到频率最高的整理成一张速查表大家可以先存一下遇到报错直接对号入座。报错信息常见原因排查动作git不是内部或外部命令PATH没配好检查环境变量Path是否包含Git的cmd目录重启终端Please tell me who you are没设置user.name和user.email执行git config --global user.name和user.emailPermission denied (publickey)公钥未登记或ssh-agent没加载私钥检查密钥是否已粘贴到代码平台执行ssh-add -l确认私钥已加载fatal: unable to access ... Failed to connect网络无法连通远程仓库检查网络连接、系统代理配置确认远程地址可访问LF will be replaced by CRLF换行符转换提示一般可以忽略若要消除需调整core.autocrlfrefusing to merge unrelated histories两个仓库历史不关联git pull时加--allow-unrelated-historiesremote: HTTP Basic: Access deniedHTTPS凭证过期或token失效更新Windows凭据管理器里的Git凭据或改用SSHno matching host key type found旧式服务器的密钥算法太老在~/.ssh/config中为该Host追加HostKeyAlgorithms配置5.2 一组容易忽视的“隐藏坑”速查表之外Windows环境还有几个问题特别容易让人摸不着头脑。第一个是git commit时莫名进入vim编辑器然后不知道怎么退出这是核心编辑器没配置导致的。解决方式是按Esc然后输入:wq但更推荐提前执行git config --global core.editor code --wait。第二个是PowerShell里使用git时中文乱码或显示问号。Git命令行本身是面向UTF-8的Windows默认代码页有时不匹配。可以在PowerShell窗口先执行chcp 65001再运行git或者在Windows Terminal的设置里把默认编码改成UTF-8问题就不复存在了。第三个是文件大小写问题。Windows文件系统默认不区分大小写但Linux区分。如果你把文件名从readme.md改成README.md在Windows上git status可能毫无反应。处理方式是在仓库根目录下配置git config core.ignorecase false同时确认文件系统没有开启大小写压缩。这个坑在跨平台项目里很容易埋雷早发现早处理。5.3 我的几个实操习惯写代码这几年我养成了一套固定的“开机后三连”习惯先打开Git Bash依次执行git config --global --list看全局配置ssh-add -l确认密钥已加载然后进入工作目录跑git status看仓库状态。这一套下来当天的工作环境基本是可靠的。其次我在新机器上配好Git之后一定会把.gitignore提前准备好。Windows开发环境常见的高危文件包括node_modules、dist、bin、obj、*.user、*.suo、Thumbs.db、Desktop.ini等不提前忽略的话一条git add .就可能把大量生成文件提交进去后续清理非常痛苦。还有一个习惯是用tig或VS Code的GitLens辅助查看历史。Git的命令行工具很强但可视化的分支图对快速理解项目演进非常有用。Windows上搭好Git之后再顺手装一个TortoiseGit或者用VS Code内置的源代码管理面板日常操作效率会有明显提升。这套Windows Git环境配置流程前前后后我重复过很多遍最深的体会是下载安装只是开始真正的功夫在配置和排查上。只要把换行符、用户身份、SSH密钥这三件事想明白了Windows下用Git的体验其实一点都不比Linux差。之后如果还要在这个环境上搭Node.js、Java或Docker那一整套开发栈Git Bash也能顺手当终端用一套流程吃透后面多少项目都稳得住。