做开发这行久了Git 基本已经和吃饭喝水一样普通。但每次帮同事或读者处理环境问题Windows 上 Git 的下载、安装、环境配置、SSH 密钥这些流程依然是问得最多的坎。很多人卡在“装是装上了一用就报错”“每次 push 都要输密码”“密钥到底怎么生成才对”。这篇文章就是把我多年实际使用中验证过的完整流程一次讲透从拿到安装包开始到装完后的全局配置、SSH 密钥生成、远程平台绑定最后再附上一份高频报错速查表。面向所有 Windows 用户不管你用的是 Win10 还是 Win11照着做基本都能一次通关。1. 动手之前先把 Windows 上的 Git 方案想清楚1.1 先确认系统架构避免装错版本Git 官方针对 Windows 提供的发行版叫 Git for Windows安装包里自带 Git Bash 终端和 Git GUI 图形界面。下载之前第一件事是确认你的系统是 64 位还是 32 位。现在的电脑绝大多数是 64 位但偶尔会遇到一些老机器或者 ARM 处理器的设备装错版本虽然不一定会直接报错但后续如果某些组件不兼容排查起来最浪费时间。最简单的检查方法按Win R输入cmd回车在命令行里执行echo %PROCESSOR_ARCHITECTURE%输出AMD64就选 64 位安装包输出x86就选 32 位。另外Windows on ARM 的设备在官网也能找到对应的 ARM64 版本普通用户直接装 64 位版即可。提示如果不确定自己的系统架构也可以在系统设置里搜索“系统信息”查看“系统类型”一栏。这一步做对了后面的安装才会顺。1.2 官网下载与可用镜像下载地址首选 Git 官网https://git-scm.com/downloads。页面会自动识别操作系统点击 Windows 就能看到当前最新版本的下载入口。官网提供64-bit Git for Windows Setup和32-bit Git for Windows Setup一般下载 64 位版就行。如果你所在网络环境下官网下载速度不理想也可以使用一些知名的公共镜像站例如阿里云镜像。直接访问https://mirrors.aliyun.com/git-for-windows/找到对应版本号的目录下载里面的Git-x.x.x-64-bit.exe文件即可。安装包通常几十 MB下载完成后最好先核对一下体积是否正常太小说明文件可能没有下载完整。这里提醒一句尽量不要下载那些来路不明的“绿色版”“精简版”Git。我见过有人图方便用了精简版结果缺少 Git LFS 组件后面克隆大项目直接失败最后还得卸掉重装。老老实实装官方完整版是所有后续配置的基础。2. 安装向导逐项解读每个选项背后都有讲究2.1 组件选择不是全勾就完事双击安装包许可协议直接 Next之后进入组件选择页面。这一屏非常关键很多人一路默认点到底问题就从这里埋下了。我建议的勾选方案是Additional icons —— 是否在桌面创建图标可选可不选属于个人喜好。Windows Explorer integration —— 建议勾选。它会在右键菜单里加入Git Bash Here和Git GUI Here实际开发中鼠标右键进入 Git Bash 是最常用也最方便的操作方式。Git LFS —— 建议勾选。如果团队里有人使用 Git LFS 管理大文件你没有这个组件clone 大仓库时会提示缺少工具。Associate .git configuration files —— 建议勾选。双击.gitconfig文件时可以直接关联到 Git 配置工具对后面对环境配置有好处。Associate .sh files to be run with Bash —— 建议勾选。Windows 上双击.sh脚本会用 Bash 来执行免去了手动选择打开方式的麻烦。Use a TrueType font in all console windows —— 建议勾选。这个选项会改善命令行里的字体显示效果中文和特殊符号不容易乱。2.2 默认编辑器、PATH、SSH 后端三个最重要的选择进入下一步后第一个大项是选择 Git 的默认编辑器。默认选项是 Vim老工程师可能觉得无所谓但一个刚接触命令行的新手如果不小心在git commit时进入 Vim 界面出来会遇到“到底怎么退出”的问题。编辑器这里我建议直接选你已经装了并且熟悉的编辑器比如 VS Code、Notepad或者 Sublime Text。如果你一个外部编辑器都没装就先保留 Vim同时在本文后面记住一个操作在 Vim 里按Esc输入:wq保存退出输入:q!不保存强制退出。接着是调整 PATH 环境变量这一项选择错误会让你在 PowerShell 或 cmd 里怎么都敲不出git命令。三个选项的区别我实际解释一下第一项仅从 Git Bash 使用 Git。选了之后git命令只在 Git Bash 里能用PowerShell 和 cmd 都识别不了。适用于系统里已经有别版本 Git 的少数场景。第二项从命令行以及第三方软件使用 Git。这是最推荐的一项。它会自动把 Git 的cmd目录加进系统 PATHPowerShell、cmd、VS Code、JetBrains 系列 IDE 都能直接调用git。第三项从命令提示符使用 Git 和相关 Unix 工具。不仅加入 Git还会把bash、ls、find等 Unix 工具覆盖进系统路径。我建议普通用户不要选这一项因为会和 Windows 自带的find.exe等命令产生冲突。然后是 SSH 可执行文件页。这里问的是“使用哪个 SSH 客户端”第一个是 Git 自带的 OpenSSH第二个是系统 Windows OpenSSH。我建议选第一个即 Git 自带的 OpenSSH。原因是版本与 Git 集成度更好而且在 Git Bash 里使用ssh-keygen、ssh-agent等命令时行为一致不容易出现密钥路径识别不了的问题。注意如果选“使用系统 OpenSSH”在 Git Bash 里执行ssh-keygen时调用的是C:\Windows\System32\OpenSSH\ssh-keygen.exe密钥和代理服务可能与 Git 自带的不一致新手容易绕晕。2.3 HTTPS 证书后端、换行符转换与终端模拟器安装向导继续往下会问 HTTPS 传输后端默认是 OpenSSL 库另一项是 Windows 内置安全通道Secure Channel。绝大多数用户保持默认 OpenSSL 即可。只有在企业内部网络使用自签名证书并且已经在 Windows 证书库里导入过自己公司证书的场景下选 Windows 内置安全通道会更省心。个人开发者完全不用纠结这里用默认值就好。换行符处理这一项是 Windows 下 Git 最容易引发困惑的设置。三种选项分别是检出 Windows 风格提交 Unix 风格的行尾符。按原样检出按原样提交。检出 Unix 风格提交 Unix 风格的行尾符。我推荐第一项。原因是 Windows 下的许多旧工具和部分文本编辑器对LFUnix 换行支持不佳第一项会在你把文件从仓库里“检出”到本地时自动转成CRLFWindows 换行保存文件后“提交”时又自动转回LF远程仓库里始终是纯LF团队里用 Windows、macOS、Linux 的同事都不会被换行符污染。如果你的团队已经全部统一用 LF那么第三项也合理但要注意未跟踪文件和已有文件可能因为行尾不一致导致整个文件 diff 变红。对新手来说第一项是最稳妥的。接下来是终端模拟器选择推荐第一项 MinTTY。它比 Windows 默认控制台窗口好用不少支持中文更正常快捷键、复制粘贴交互也更友好命令行体验与 Linux 终端更接近。第二项是 Windows 自带的控制台窗口conhost如果你习惯了 cmd 的操作方式选它也完全能用但对大多数新手MinTTY 的学习成本更低。2.4 pull 行为、凭证管理器与杂项配置git pull的默认行为有 merge 和 rebase 两个选项。默认是 merge新手建议保留默认。merge 的操作方式更容易理解分支历史虽然会有分叉节点但不会破坏已有提交。如果你已经熟悉 rebase 工作流可以改成 rebase让提交历史更线性化。这个设置后续也可以用git config --global pull.rebase true/false随时调整所以安装时不用太焦虑。凭证管理器那里默认勾选了 Git Credential ManagerGCM。这个组件建议一定要保留它有图形界面弹窗会帮你记住 HTTPS 协议的账号或访问令牌避免在命令行里反复输入 GitHub、GitLab 的密码。后面我会在 SSH 方案里另外讲这里留个印象。最后的附加配置里文件系统缓存的勾选保留即可这项能提升文件状态检查速度符号链接在 Windows 下默认不推荐勾选因为创建符号链接需要额外权限普通用户勾了之后反而会出现奇怪的问题保持默认关闭就好。2.5 安装完成后的第一眼检查等待进度条走完安装成功的标志是桌面或文件夹右键菜单里出现了Git Bash Here和Git GUI Here。如果菜单里看不到可能是右键菜单项注册失败重启一次资源管理器通常能解决。打开 Git Bash执行git --version看到类似git version 2.x.x.windows.x的输出就说明安装核心部分已经完成。如果这一步报“找不到命令”基本可以确认在 PATH 选择那一步选了第一项回头重装一次或者按我第 5 部分的方法手动补环境变量即可。3. 环境配置与基线设置装完不乱才行3.1 命令行入口Git Bash、Git CMD、PowerShell 怎么选Git 装完后Windows 上会有多个入口。我最推荐日常开发使用 Git Bash因为它的命令风格贴近 Linux 环境ls、grep、ssh、vim这些工具都有并且路径会转换为/c/Users/你的用户名这样的形式在写脚本和命令时比 Windows 路径少很多转义问题。Git CMD 是让习惯 cmd 的人使用的入口功能上没区别但它没有 Bash 语法环境。PowerShell 用户则直接打开终端执行git前提是你安装时 PATH 选的是第二项。我个人的习惯是在 IDE 里用集成终端操作 Git在独立工程项目里直接用 Git Bash。看你自己习惯工具本身不冲突重点是把基础配置做对。3.2 身份信息配置user.name、user.email 绕不开Git 每次提交文件时都会记录提交人信息这个信息不是从系统账号里读取的而是读取你配置的user.name和user.email。如果不配置第一次 commit 时 Git 会报错提示你补上。配置命令如下git config --global user.name 你的名字 git config --global user.email 你的邮箱注意两点。第一--global表示当前用户全局生效如果不加就只对当前仓库生效。第二user.email建议与你在 GitHub、GitLab 等平台的账号邮箱保持一致。拿 GitHub 举例提交记录通过邮箱关联到你的账号头像和 contribution 热力图才会正确显示。邮箱不一致的话提交虽然成功但在网站上不会归到你的用户名下后面想改历史记录很麻烦。3.3 高频全局配置清单一次设好省心很久身份信息只是第一步。以下这些是我实际使用中验证过的高频全局配置建议手动执行一遍。# 新仓库默认分支名设为 main git config --global init.defaultBranch main # 如果你安装时选了 CRLF 转换这里保持默认即可可再确认一下 git config --global core.autocrlf true # 让中文文件名在 git status 里正常显示而不是显示成八进制转义 git config --global core.quotepath false # 让 Git 追踪文件名大小写变化Windows 文件系统默认不区分大小写 git config --global core.ignorecase false # 凭证管理记住 HTTPS 凭据 git config --global credential.helper manager # 查看所有配置 git config --global --listcore.quotepath false是非常实用的一个配置。Windows 上如果你的仓库里有中文文件名不做这个设置执行git status时会看到类似\346\265\213\350\257\225.txt这种乱码字符串。设置之后中文正常显示。core.ignorecase也很关键Windows 文件系统对大小写不敏感但 Git 内部是敏感的如果你把Readme.md改成README.md不设置这一项Git 可能完全察觉不到变化。3.4 把配置沉淀成自己的 .gitconfig所有全局配置最终都会写入用户目录下的.gitconfig文件。Windows 下它的位置是C:\Users\你的用户名\.gitconfig。这个文件是纯文本你完全可以手动编辑。我贴一份常见的模板[user] name Your Name email yourexample.com [core] autocrlf true quotepath false ignorecase false editor code --wait [init] defaultBranch main [pull] rebase false [credential] helper manager [diff] tool vscode文件里的core.editor如果设置为code --wait表示默认编辑器用 VS Code并且在git commit时等待 VS Code 窗口关闭才继续执行。注意一点如果要用这个配置得保证 VS Code 的code命令已经加入了 PATH。在 VS Code 里按CtrlShiftP输入Shell Command: Install code command in PATH执行一次就能搞定。4. SSH 密钥从零到一Git 远程连接的完整闭环4.1 为什么值得用 SSH 而不是 HTTPSclone 远程仓库一般有两种协议HTTPS 和 SSH。HTTPS 配置简单但每次 push 要么输密码要么依赖凭证管理器弹窗如果账号开了二次验证还要用 Personal Access Token 代替密码刚上手的人很容易在这里卡住。SSH 协议的核心思路是配置一次密钥后续 push、pull 都不需要输密码。原理其实不复杂密钥是一对文件一个公钥、一个私钥。公钥放到远程代码平台GitHub、GitLab、Gitee 都有对应入口私钥自己保存在本机。连接时远程平台通过密码学握手确认你的私钥确实匹配公钥验证通过就直接放行。这就像你给自己家配了一把钥匙门锁公钥装在服务器上自己手里留了一把钥匙私钥只要钥匙对应门就能开。4.2 生成密钥前先检查是否已有存量密钥执行下面命令查看当前用户目录下有没有已经生成的密钥ls -al ~/.ssh如果看到id_ed25519和id_ed25519.pub或者id_rsa和id_rsa.pub说明你之前生成过密钥。这时你可以考虑直接复用旧密钥把对应的.pub公钥内容添加到新平台即可如果不放心旧密钥的安全性也可以重新生成然后用新公钥替换各平台的记录。4.3 用 ssh-keygen 生成第一把密钥在 Git Bash 里执行生成命令ssh-keygen -t ed25519 -C your_emailexample.com-t ed25519指定密钥类型Ed25519 是目前在签名速度和安全性上都很均衡的算法支持它的平台也越来越普遍。如果你的远程服务器或 Git 服务版本比较老兼容性有问题再改用 RSAssh-keygen -t rsa -b 4096 -C your_emailexample.com执行后会提示你确认保存路径默认是~/.ssh/id_ed25519直接回车用默认即可。接着会让你设置 passphrase口令。这一步很多人拿不准要不要填。我的建议是在个人电脑上如果不怕麻烦设置一个口令安全性更好即使私钥文件泄露别人也解密不了当然口令会在每次使用密钥时被要求输入为了不烦人可以配置 ssh-agent 在会话中帮你记住口令。如果你图省事直接留空也是可以的但私钥文件一旦泄露就等于裸奔。生成完成后.ssh目录下会出现两个文件id_ed25519是私钥留在本机绝对不要发给任何人id_ed25519.pub是公钥可以放心添加到各远程平台。4.4 添加公钥到 GitHub、GitLab、Gitee查看公钥内容可以用cat ~/.ssh/id_ed25519.pub更高效的方法是直接把内容复制到剪贴板clip ~/.ssh/id_ed25519.pub执行完clip命令后CtrlV就能把公钥粘贴到任意位置。然后登录你的代码托管平台找到 SSH keys 的设置入口GitHub右上角头像 - Settings - SSH and GPG keys - New SSH key。GitLab点击头像 - Edit Profile - SSH Keys。Gitee头像 - 设置 - SSH 公钥。把公钥内容粘贴到 Key 输入框Title 随便写一个便于识别的名字比如my-windows-laptop保存即可。这里有个小细节粘贴时注意前后不要有多余空格很多失败案例是复制时把换行符也一起粘进去了。4.5 启动 ssh-agent 并验证连接ssh-agent 是一个帮你管理私钥、避免每次使用都输入 passphrase 的后台服务。在 Git Bash 里启动eval $(ssh-agent -s)然后添加私钥ssh-add ~/.ssh/id_ed25519如果你设置了 passphrase此时会要求输入一次后续这个终端会话内就不需要重复输入了。验证到 GitHub 的连接ssh -T gitgithub.com首次连接会出现一条确认主机指纹的提示输入yes回车看到类似Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.的信息就说明密钥配置全程已打通。Gitee 的验证命令是ssh -T gitgitee.comGitLab 则把域名替换成你实际使用的地址。4.6 多平台多账号时用 config 文件隔离密钥如果你有多个代码平台的账号或者一台电脑上要用两套不同的密钥比如一套 GitHub 个人项目用一套公司 GitLab 用直接把不同密钥都加到远程平台后Git 连接时用的是默认的id_ed25519你会发现另一个账号连接不上。解决办法是在~/.ssh/config文件里写清楚规则# GitHub 个人账号 Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal # GitLab 公司账号 Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work配置后执行ssh -T gitgithub.comGit 会根据 Host 里写的域名自动选择对应的私钥两个平台切换互不干扰。这个文件可以手动创建注意不要加多余空格否则可能解析失败。5. 高频问题与解决实录这些都是真实踩过的坑5.1 “git 不是内部或外部命令”这基本是 PATH 选择不对导致的。安装完成后在 cmd 里执行git如果提示命令找不到说明 Git 的cmd目录没有加入系统 PATH。解决办法有两个重新运行安装程序选择 Modify把 PATH 选项改成第二项。手动补环境变量右键“此电脑” - 属性 - 高级系统设置 - 环境变量编辑用户变量的Path新增C:\Program Files\Git\cmd然后重启终端。需要注意修改环境变量后要新开终端窗口才会生效在旧窗口里执行永远看不到变化。5.2 老是提示输入用户名密码或者 Permission denied先判断自己 clone 时用的是 HTTPS 还是 SSH。如果远程地址是https://github.com/...那每次 push 提示输入用户名密码是正常的。解决思路要么配置凭证管理器让它记住git config --global credential.helper manager要么改用 SSH 方式连接把 remote 远程地址改成 SSHgit remote set-url origin gitgithub.com:用户名/仓库名.git如果提示的是Permission denied (publickey)优先检查三件事一是确认公钥已经加到平台二是确认ssh-add -l能看到你的私钥三是用ssh -vT gitgithub.com输出详细日志看是哪一步失败这一步能清晰看出 Git 实际尝试的密钥文件是哪个。5.3 中文文件名乱码、status 里全是奇怪符号这个问题十有八九是core.quotepath没有设置。执行git config --global core.quotepath false然后再看git status中文文件名就正常了。如果终端本身乱码还要确认 Git Bash 的语言环境可以在 Git Bash 里执行echo $LANG正常应该输出zh_CN.UTF-8或en_US.UTF-8。5.4 换行符引起的整个文件 diff 全红场景是这样的你在 Windows 上改了文件提交时发现 diff 里整个文件都变了哪怕只改了一行。这是core.autocrlf不一致导致的。如果本地配置是false仓库里原本是 LF你编辑时某次保存成了 CRLFGit 就认为整个文件的所有行都被修改了。处理办法是统一配置git config --global core.autocrlf true假如仓库已经混入了一堆 CRLF需要重新规范化行尾可以在仓库根目录执行git add --renormalize . git add -u git commit -m normalize line endings更规范的做法是在仓库根目录添加.gitattributes文件显式声明文本文件统一使用 LF* textauto *.js text eollf *.md text eollf有了这个文件所有开发者不管在什么系统上检出和提交行为都会被 Git 强制统一从根上避免换行符问题。5.5 其他几个容易忽略的小问题Git Bash 里打开 VS Code 提示找不到命令先检查是否执行过Shell Command: Install code command in PATH。Windows 自带的 OpenSSH 服务和 Git 自带 SSH 冲突时优先保持一种 SSH 工具链别混用。杀毒软件偶尔会拦截 Git 的安装进程遇到安装中断先关闭实时监控再重试。另外安装路径不要放在带中文或空格的目录下默认路径C:\Program Files\Git没有中文是最稳的。这几个问题都是我在实际使用中碰过壁的尤其换行符那个曾经在一个团队项目里导致大量无效 diff最后靠.gitattributes才彻底解决。如果你也遇到类似情况别慌按上面的步骤一步步检查基本都能恢复。最后再分享一个我个人的习惯SSH 私钥在我看来和银行卡密码是同一个级别的敏感信息所以我会给私钥设置 passphrase并且在换电脑时只迁移公钥到新平台私钥通过加密导出而不是直接明文拷贝。配置好之后我通常会在新环境里先完整走一遍ssh-keygen、启动 ssh-agent、ssh -T gitgithub.com验证连接全流程确认无误后再开始克隆项目。这套方法虽然前期多花几分钟但后面每次 push、pull 都顺畅得多值得养成习惯。