开年这一摊子事忙完又到了给新电脑做开发环境的时候。这几天后台一直有人问Windows下Git到底怎么装、怎么配、SSH密钥怎么弄才能不每次输密码。正好我前两天刚把一台新Windows机器从零到一完整走了一遍顺手把整个过程整理成这份教程从下载安装包一直写到GitLab和GitHub的SSH密钥配置每一步都有截图级的说明和实际操作命令照着敲就行。这篇文章覆盖的完整链路是Git for Windows的下载与安装、安装完成后的基础环境验证、用户名邮箱等全局配置、SSH密钥对的生成与多平台托管、常见报错排查。适合刚接触Git的初学者也适合那些已经装了Git但一直没搞懂SSH配置的开发者。我会把每个环节“为什么这么做”也讲清楚不是单纯给命令这样你以后再遇到相关问题也有排查思路。1. 下载与安装选对版本别让第一步就翻车1.1 从官方渠道下载Git for WindowsGit官方下载页面是https://git-scm.com/download/win页面会自动识别Windows系统并给出最新的64位安装包。目前2026年的最新稳定版本已经迭代到2.44以上系列安装包体积大概在60MB左右整个安装过程就两三分钟不存在什么门槛。这里有个容易踩坑的地方不要从非官方渠道下载所谓的“加速版”“精简版”Git那些第三方打包的版本可能捆绑了推广软件或者修改了内置的OpenSSH组件后续配置SSH密钥时会出现各种莫名其妙的报错。我一直建议直接从git-scm官网或者可靠的软件源下载官网版本干净、组件齐全后续省心得多。另外注意一下系统架构。现在绝大多数Windows机器都是x64架构但如果你用的是ARM架构的Windows笔记本比如部分骁龙芯片设备下载页面会提供对应的ARM64安装包。装错架构的话Git虽然也能运行但会通过模拟层跑性能有损耗而且个别组件行为会不一样。提示在下载页面可以选择自己需要的版本号和安装包格式。如果官网下载速度不理想可以用国内高校或云厂商的镜像站版本号对着官网选同一版本就行校验哈希值一致即可放心安装。1.2 安装向导的关键选项逐个拆解双击安装包后会进入Git Setup向导。安装向导有十几步大部分选项保持默认即可但有四个关键步骤值得单独拿出来分析。第一步选择安装路径。默认是C:\Program Files\Git我一般会改到D:\Tools\Git这类非系统盘目录主要是重装系统时不用重新下载配置同时避免Program Files目录的权限限制偶尔带来的麻烦。路径最好不要包含中文和空格虽然新版Git已经兼容但后续一些第三方工具调用Git时仍可能因为路径问题抽风。第二步选择组件。这里有几个可选项需要关注Git Bash Here和Git GUI Here右键菜单选项建议保持勾选日常操作非常方便。Add a Git Bash Profile to Windows Terminal选项建议勾选新版Windows Terminal集成后可以在终端里直接打开Git Bash体验比单独窗口好很多。Scalar这个组件是对大仓库的优化工具建议勾选上用不上也不碍事。第三步选择默认编辑器。这一步很多人直接默认选Vim但我知道对新手来说Vim的编辑器操作完全不是人用的。如果你电脑上已经装了VS Code强烈建议在这一步选择Select Visual Studio Code as Gits default editor没装的话也可以选Notepad总之选一个你自己会用、能关掉的编辑器就行。否则万一提交信息写错要修改时弹出一个Vim窗口不会退出那感觉确实很崩溃。第四步调整PATH环境变量。这里有三个单选项Only use Git from Git BashGit命令只在Git Bash里可用比较隔离但不推荐。Git from the command line and also from 3rd-party software把Git加入了系统PATHCMD、PowerShell、VS Code终端都能直接用git命令这是推荐选项。Use Git and optional Unix tools from Command Prompt会把Git的Unix工具也加进系统PATH容易和Windows自带命令冲突不建议。后续几个页面包括SSH客户端选择、换行符转换方式、终端模拟器选择等我在下文对应环节会单独讲这里直接默认并往后走基本没问题。1.3 一个更省事的安装方式命令行静默安装如果你需要批量在多台机器上安装Git或者单纯不想一路点“Next”可以用winget来装winget install --id Git.Git -e --source winget这个命令会直接拉取最新稳定版Git并静默安装安装完成后同样出现在开始菜单中。winget安装版默认采用的安装选项和图形界面里的推荐配置基本一致唯一要留意的是它默认不会勾选“右键菜单”相关选项如果你依赖右键Git Bash Here装完还要手动打开安装包改一次或者在注册表里补上。顺带提一句如果你公司内网有软件分发系统也可以用/VERYSILENT /NORESTART参数把安装包静默执行参数和Windows普通安装程序一致Git-2.44.0-64-bit.exe /VERYSILENT /NORESTART这种方式适合IT管理员给全公司推送Git环境普通个人用户意义不大但知道有这么一条路总是好的。2. 基础环境配置装完不等于配好2.1 验证安装结果装完之后先别急着用打开一个CMD或PowerShell窗口验证一下安装是否完整。输入git --version如果输出类似git version 2.44.0.windows.1说明Git主程序已经正常。接着验证内置的SSH客户端是否可用ssh -V正常会输出类似OpenSSH_9.7p1, OpenSSL 3.2.1的信息。这一步很多人会忽略但SSH密钥配置全依赖这个组件如果提示“不是内部或外部命令”说明你的Git安装有问题或者PATH配置没生效需要检查一下环境变量。另外我建议顺手验证一下Git Bash的完整性。在开始菜单打开Git Bash输入ls -la ~如果能看到自己的用户目录列表说明Git Bash工作正常。这一步因为牵涉到家目录的指向后面SSH配置也在这个目录下提前确认好可以少走弯路。2.2 设置user.name和user.email这是所有Git配置里最基础但最容易忽略的一步。Git每次提交时都会把提交者的用户名和邮箱写入提交记录如果你没有设置全局身份信息首次提交时会提示Please tell me who you are并拒绝执行。打开Git Bash依次执行git config --global user.name Your Name git config --global user.email your_emailexample.com这里的Your Name建议用拼音或英文昵称避免中文在部分终端显示乱码邮箱建议使用你注册GitHub/GitLab/Gitee时用的同一个邮箱这样提交记录能正确关联到你的账号头像和主页。设置完之后可以用下面命令查看全局配置是否生效git config --global --list这个命令会列出所有全局配置项。除了用户名和邮箱还能看到core.autocrlf、init.defaultbranch等默认配置这些在后面都会涉及。这里要额外提醒一点user.name和user.email可以按仓库单独覆盖。比如你在公司用的邮箱是zhangsancompany.com个人项目用zhangsangmail.com可以在某个仓库目录下不添加--global参数重新执行一次配置仓库内的本地配置优先级高于全局配置。这种“全局兜底本地覆盖”的模式是Git配置体系的核心设计思路理解了这个层级关系后续调整配置时就能得心应手。2.3 换行符与默认分支名的隐患处理Windows和Unix系统对文本换行的处理方式不一样Windows用CRLF回车换行Linux/macOS用LF换行。Git有一个专门处理这个差异的配置项叫core.autocrlf。在Windows上安装Git时安装向导会默认选择“Checkout Windows-style commit Unix-style line endings”翻译过来就是core.autocrlftrue。这个配置的含义是拉取代码时Git自动把LF转成CRLF提交代码时自动把CRLF还原成LF。好处是仓库里始终保存LFWindows工作区里则是CRLF两边都不会出问题。但这里有个比较典型的坑如果你用VS Code或其他编辑器修改文件时不小心把整个文件的换行符都变成了CRLF或LF提交时Git会提示warning: LF will be replaced by CRLF或反之。这通常是正常提示不代表提交失败也不需要过度担心。真正要命的是项目中同时存在两种换行符的文件导致每次diff都显示全文件变更这种问题排查起来通常需要大量时间。我个人的习惯是把core.autocrlf设为false然后用EditorConfig或项目内的.gitattributes文件来统一管理换行符。团队协作时由.gitattributes声明哪些文件用LF、哪些文件用CRLF依赖Git的归一化机制来自动转换比单纯依赖每个人的本机配置可靠得多。再提一个默认分支名的问题。新版Git安装时会让选择默认分支名称默认是master但主流代码托管平台已经普遍默认用main。我建议在安装后在全局配置里改一下git config --global init.defaultBranch main这样在本机git init新仓库时默认分支就是main和GitHub/GitLab的新建仓库保持一致省去以后手动改名或两边分支对不上的麻烦。3. SSH密钥的完整配置从生成到多平台托管3.1 为什么必须用SSH密钥而不是密码访问GitHub、GitLab这些远程仓库时有两种主流认证方式HTTPS账号密码和SSH密钥。HTTPS方式在克隆私有仓库时需要输入用户名和密码现在普遍改成了Personal Access Token每次推送都要输入非常影响操作流程度。而SSH密钥是一对非对称加密密钥私钥保存在本地~/.ssh/目录下公钥上传到代码托管平台。后续访问时Git会用私钥签名、服务器用公钥验签全程不需要再输密码。从安全角度讲SSH密钥也比密码更安全私钥永远不会离开你的电脑而且可以额外设置口令passphrase保护即使私钥文件被人拷走没有口令也无法使用。为了应对不同托管平台你甚至可以准备多对密钥比如一个密钥专门用GitHub另一个专门用GitLab公司账号互相隔离。这个后面在3.4节会专门讲多账号配置方法。3.2 生成密钥对命令与参数详解在Git Bash中执行下面的命令生成密钥对ssh-keygen -t ed25519 -C your_emailexample.com这里拆开解释一下各参数-t ed25519指定密钥算法为Ed25519这是目前安全性和性能都比较均衡的算法生成的密钥长度短兼容性在现代系统中也已经很好。-C your_emailexample.com添加注释通常填你的邮箱方便在托管平台上识别这个密钥是哪个设备哪个用户创建的。生成后Git Bash会问你保存位置Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):直接回车使用默认路径即可。接下来会提示输入passphrase口令这里可以做两个选择直接按两次回车表示不设置口令。好处是后续使用完全免密坏处是私钥文件暴露后风险较高。输入一个口令。好处是即使私钥文件泄露也无法直接使用坏处是每次使用SSH连接时都要输一次口令不过我们可以借助ssh-agent来缓存口令后面细说。我个人建议机器是个人独立使用且不担心丢失的话可以是空口令但凡电脑可能外借、公司统一管理、或存放了高权限的部署密钥一定要设置口令。生成完成后检查一下有没有生成两个文件ls -la ~/.ssh/正常能看到id_ed25519私钥和id_ed25519.pub公钥。永远不要把私钥文件暴露在截图、日志或任何网络传输里公钥则随便分发没有问题。如果某些老旧的代码平台不支持Ed25519算法也可以用RSA算法生成ssh-keygen -t rsa -b 4096 -C your_emailexample.com-b 4096表示密钥长度4096位。RSA兼容性极广但密钥文件更长加解密速度也稍慢现阶段优先用Ed25519。3.3 配置GitHub和GitLab公钥上传与本地验证公钥怎么上传到平台以GitHub举例用下面命令复制公钥内容注意是.pub文件不是私钥cat ~/.ssh/id_ed25519.pub登录GitHub进入Settings - SSH and GPG keys - New SSH key。Title填一个能分辨设备的名称比如work-laptop或home-pcKey Type选Authentication Key然后把复制的公钥内容粘贴到Key输入框保存。GitLab的流程类似Settings - SSH Keys把公钥粘贴进去填好标题和过期时间即可。上传完公钥后别急着克隆代码先验证一下链路通不通ssh -T gitgithub.com首次连接时会有主机指纹确认提示The authenticity of host github.com (IP) cant be established. ED25519 key fingerprint is SHA256:xxxxxx. Are you sure you want to continue connecting (yes/no/[fingerprint])?输入yes回车。如果配置正确GitHub会回复Hi username! Youve successfully authenticated, but GitHub does not provide shell access.GitLab的验证命令给个对应的ssh -T gitgitlab.com成功会提示Welcome to GitLab, username!。Go语言里的Gitee、Bitbucket等平台的验证思路也一样无非是换一下域名和用户名前缀都是git开头。注意这里的gitgithub.com用的是git这个固定用户名不是你的GitHub账号名。SSH协议在Git服务里的git用户是通用入口服务端会根据你的公钥识别你是哪个用户。3.4 多账号多平台的SSH配置很多人工作和个人项目会用不同的账号比如公司GitLab一个账号、个人GitHub另一个账号。如果共用一对密钥虽然也能访问两个平台但同一个公钥挂在两个账号下管理上说不清楚也不安全。更麻烦的场景是两个不同平台都使用git用户名连接Git默认会用同一把私钥去握手一旦平台不接受连接就失败。解决方法是使用~/.ssh/config配置文件把不同的Host映射到不同的私钥。假设你在GitHub用id_ed25519_github在GitLab用id_ed25519_gitlab先生成两对密钥然后在~/.ssh/config里这样写Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/id_ed25519_gitlab这里每个配置块里最关键的是IdentityFile指定了对应私钥路径User git则是所有Git服务平台的固定SSH用户名。写完后记得给配置文件添加权限Windows下一般不用管如果是Linux或macOS需要chmod 600 ~/.ssh/config然后用ssh -T分别验证两个Hostssh -T gitgithub.com ssh -T gitgitlab.com两边都通过Authentication即可正常克隆和推送。注意克隆地址要用gitgithub.com:owner/repo.git这种SSH格式而不是https://github.com/owner/repo.git那种HTTPS格式。这里还涉及到ssh-agent的一个小细节。如果你给私钥设置了passphrase每次SSH连接都可能要求输入口令。可以把私钥加进ssh-agent让它缓存口令eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519之后在当前会话内使用SSH就免密了。重启电脑后ssh-agent会清空缓存需要重新ssh-add。Windows下如果觉得麻烦可以直接在Git Bash的快捷方式属性里设置启动时自动运行ssh-agent然后把上述命令写进~/.bashrc这样每次打开Git Bash都能自动加载。# 在 ~/.bashrc 中追加 eval $(ssh-agent -s) /dev/null 21 ssh-add ~/.ssh/id_ed25519 2/dev/null3.5 旧算法连接失败的应对2022年以后OpenSSH 8.8版本默认禁用了基于SHA-1的RSA签名算法ssh-rsaWindows版Git自带的OpenSSH也随之受影响。如果你遇到类似Unable to negotiate with xxx port 22: no matching host key type found的报错大概率是服务端还在用旧算法。解决方法有三个层面最直接的是让服务端升级SSH配置启用更现代的密钥交换算法但这个往往不是你能决定的。如果你使用的是比较老的企业GitLab或内部服务器可以先在服务端改用Ed25519公钥如果服务端SSH版本较新的话这样客户端默认就能连通。如果服务端确实无法升级可以在客户端~/.ssh/config中临时加上兼容参数Host old-server HostName 192.168.1.100 User git IdentityFile ~/.ssh/id_rsa_old HostKeyAlgorithms ssh-rsa PubkeyAcceptedAlgorithms ssh-rsa这种方案属于临时兼容手段不太建议长期依赖等服务器升级后应及时移除。4. Git Bash与终端工作流的整合技巧4.1 为什么推荐Git Bash而不是CMD或PowerShellWindows的CMD对Unix命令支持很差PowerShell虽然功能强但很多Git相关的Unix命令如ls、grep、cat在PowerShell里的行为和预期不一致。Git Bash提供了一个模拟Unix shell的环境内置了bash、ssh、ls、grep、awk等常用工具在Windows上做Git操作时体验最接近Linux/macOS。如果你之前完全没用过命令行直接上手Git Bash是最平滑的路径。它是独立窗口可以调整字体和颜色不用担心和系统cmd冲突。当然如果你更熟悉PowerShell也可以直接把Git的bin目录加入PATH在PowerShell里使用git命令。但注意不要在PowerShell里依赖ls等别名的输出格式做脚本自动化被坑过之后你就懂我的意思了。4.2 把Git Bash集成到VS Code和Windows Terminal现在大部分开发者都在VS Code里写代码提交Git操作也用VS Code自带的源码管理面板。插件和面板的底层都是调用本机的git命令所以只要PATH配置正确VS Code几乎不需要额外配置就能识别Git。如果你希望在VS Code里打开一个内置终端来跑Git命令默认终端可以切换成Git Bash按Ctrl Shift P打开命令面板。输入Terminal: Select Default Profile选择Git Bash。以后打开终端就是Git Bash环境git命令、ssh命令都能直接跑。Windows Terminal也一样在设置里添加一个新配置文件命令行指向C:\Program Files\Git\bin\bash.exe注意不是git-bash.exe后者是启动Git Bash窗口的快捷方式前者才是bash解释器再把配置文件设为默认就能获得一个标签页版Git Bash。VS Code的集成终端里使用SSH远程开发Remote-SSH时也需要本地已经安装SSH客户端Windows版Git自带的OpenSSH完全可以胜任这个角色。4.3 Git命令行常见高频操作速查配置好环境之后把日常最高频的几条命令列在这里方便复制使用# 查看状态 git status # 查看当前分支 git branch # 拉取远程更新 git pull origin main # 提交 git add . git commit -m feat: 描述内容 # 推送 git push origin main # 查看提交历史 git log --oneline --graph --all新手容易搞混的是fetch和pull的区别fetch只下载远程提交到本地远程跟踪分支不动工作区pull等于fetch加merge会直接更新工作区代码。多人协作时建议先git fetch然后自己git diff看一下差异再决定怎么合并不要闭眼pull否则容易产生大量无意义的合并提交。5. 常见问题与排查技巧实录5.1 SSH连接失败Permission denied与Host key verification failed这是SSH配置中遇到最多的两类报错。Permission denied (publickey)字面意思是公钥认证失败。排查步骤按顺序来确认公钥已经正确粘贴到托管平台。复制公钥时不要把多余的换行符或空格带进去粘贴后看看末尾是否完整。确认本机使用的私钥路径和平台上的公钥是否是一对。生成多对密钥时很容易搞混用ssh-add -l查看当前agent中加载的密钥指纹再去平台核对公钥指纹是否匹配。检查~/.ssh/config里有没有配置错误的Host块。如果IdentityFile指定了一个不存在的私钥路径也会导致同样的报错。用ssh -vT gitgithub.com打开调试模式会输出详细的协商过程重点看Offering public key这一行之后有没有服务端返回的成功提示。Host key verification failed这种情况通常是因为远程主机指纹发生变化常见于服务器重装系统后IP复用或者你连接了一个之前从未见过的主机名。解决办法是编辑~/.ssh/known_hosts删除对应主机的旧指纹记录然后重新连接确认新指纹。ssh-keygen -R github.com-R可以清除指定主机的known_hosts记录。如果要手动指定known_hosts文件路径可以加-f参数不过一般用不上。5.2 换行符警告与文件权限差异像前面提到的LF will be replaced by CRLF警告大多数情况下不用处理。如果你希望彻底消除这种噪声建议在仓库根目录添加.gitattributes文件显式声明统一规则* textauto *.sh text eollf *.bat text eolcrlf *.png binary这个文件随仓库一起提交所有协作者拉下来后都会遵循同一份换行符规则。另一个Windows常见的问题是文件权限。普通用户一般感知不到但如果你在Windows上创建了一个shell脚本比如deploy.sh提交到Git后在Linux服务器上执行时提示权限不够这是因为Git记录的100644文件模式没有执行权限。可以用下面命令补上git update-index --chmodx deploy.sh然后提交一次Git会记录文件为100755模式Linux拉下去就能直接执行。5.3 Git中文乱码问题Windows下Git日志和终端的中文显示乱码是老问题了。主要有两个层面日志乱码git config --global core.quotepath false git config --global i18n.logoutputencoding utf-8文件名字符乱码特别是中文文件名显示成\345\274\240这种八进制转义用core.quotepath false解决。命令输出乱码则可能是Git Bash窗口本身的编码问题右键窗口标题栏 - Options - Text把字符编码改成UTF-8即可。如果项目文件编码本身不是UTF-8比如老项目用的GBK这个就不是Git配置层面能解决的了需要先在编辑器里统一转成UTF-8再提交。5.4 其他高频问题的速查表问题现象可能原因解决思路git push提示超时或无法连接远程仓库网络不通或端口22被防火墙拦截用ssh -vT gitgithub.com检查网络链路实在不行改用HTTPS方式克隆需要配置凭据管理器git pull报The file will have its original line endings换行符配置混乱按.gitattributes规则统一换行符必要时执行git add --renormalize .执行git提示“无法将git识别为cmdlet”PATH缺失检查安装时是否选了“Git from the command line”选项或手动把Git\cmd目录加入系统PATHssh提示Bad owner or permissionsWindows下用户目录权限被修改把~/.ssh目录权限重置为仅当前用户可读可在Git Bash中执行chmod 700 ~/.ssh chmod 600 ~/.ssh/*登录GitHub时总是要求输密码可能clone时使用了HTTPS地址或SSH密钥没配置确认仓库remote地址是gitgithub.com:...格式或配置credential helper5.5 配置验证的完整操作一览最后给大家一套完整的验证流程每次配好新环境后按顺序过一遍基本能确认整条链路都正常# 1. 检查Git版本 git --version # 2. 检查SSH客户端 ssh -V # 3. 检查全局配置 git config --global --list # 4. 检查密钥文件是否齐全 ls -la ~/.ssh/ # 5. 检查ssh-agent服务是否在跑 echo $SSH_AUTH_SOCK # 6. 验证GitHub连接 ssh -T gitgithub.com # 7. 验证GitLab连接如果有的话 ssh -T gitgitlab.com # 8. 克隆一个测试仓库试试全流程 git clone gitgithub.com:owner/hello-world.git如果每一条都顺利通过说明你的Windows Git环境就完全配好了。后面不管是clone开源项目、推送自己的博客源码还是参与公司团队协作都不会再被环境问题绊住脚。整个配置过程大概15分钟但换来的是之后每天的流畅操作这笔时间投入非常划算。最后再分享一个我个人的小习惯配好环境后我会把git config --global --list的输出存一份快照哪天换了新电脑或者环境被搞乱了对照这份快照再配一遍就不会遗漏任何自定义项。你也不妨试试。