Windows下Git安装配置与SSH密钥设置全攻略：从0到1环境搭建

很多人第一次在 Windows 上装 Git以为就是一路点“下一步”装完就万事大吉。结果打开终端敲git --version系统直接回一句“不是内部或外部命令”搞了半天终于能敲命令了想git push代码到远程仓库又撞上Permission denied (publickey)。你说难受不难受这篇教程就是冲着这些问题去的。我会顺着 Windows 环境下 Git 的完整落地路径把下载、安装、环境配置、SSH 密钥生成与配置这些环节逐个拆开每一处关键选项都说明它背后的意义每一条命令都给出可以直接复制的写法。内容面向零基础用户也兼顾已经装过 Git 但环境配置一直不清不楚的朋友按章节走一遍以后遇到类似问题至少知道去哪里排查。1. 下载安装前先弄清版本与渠道避免装了个“假 Git”网上搜 Git 下载结果特别杂。有些网站标题写着“Git 官方中文版”点进去是个陌生下载站有些说是“精简版”“绿色版”体积小得可疑。这里先说结论在 Windows 上认准Git for Windows这一个项目就够了。它是在 Windows 原生环境下运行 Git 的事实标准由社区持续维护覆盖了从命令行工具到 Git Bash、Git GUI 的全套能力。1.1 官网下载与软件源镜像怎么选Git 官网下载页面会直接检测你的操作系统一般进入后就能看到 Windows 版本的下载按钮。正常情况下官网下载是最稳妥的文件名类似Git-2.x.x-64-bit.exe数字代表具体版本号。但在某些网络环境下官网下载速度可能比较慢。替代方案是使用国内高校或云厂商维护的软件源镜像站比如清华大学的开源软件镜像站、阿里云的镜像站。这类镜像提供的是官方安装包的副本哈希值一致不需要担心被二次打包。我自己测试过镜像站速度通常比官网快很多下载完顺手校验一下文件属性里的数字签名确认“发布者”显示为 Git 的维护组织即可。需要特别提醒的是不要使用那些“绿色便携版”“中文定制版”。Git 的安装逻辑本身不复杂便携版反而容易缺失后续升级所必需的注册表项或 PATH 环境变量配置一旦出问题排查成本比自己安装高得多。1.2 64 位还是 32 位现在的电脑基本都是 64 位 Windows 11 或 Windows 10。如果你不确定打开“设置—系统—系统信息”查看“系统类型”这一栏就行。只要不是十几年前的旧机器都选 64 位安装包。只有一个例外情况如果你需要在极度精简的 32 位 Windows 环境里使用才考虑 32 位安装包。其余情况闭眼选 64 位性能和兼容性都更好。2. 安装向导中的关键选项逐项拆解双击安装包后真正的“坑”才开始。安装界面默认是英文很多新手看到英文界面就紧张其实它每一步都有说明。我按安装顺序把几个需要认真对待的选项挨个讲一遍。2.1 首次安装时填写的用户名和 email 到底影响什么安装过程中期会出现一个界面标题大致是Configuring the line ending conversions之类但在这之前还有个容易被忽略的步骤让你填写user name和email。这里填好的内容会直接写入 Git 的全局配置作为你后续每一次提交记录的“作者身份”。我遇到过不少刚接触 Git 的朋友在这里随手填了拼音、昵称甚至一串乱码。这些内容最终会出现在提交历史里如果以后代码要开源或者交给公司就会显得很不专业。建议现在就决定好一个公开的英文用户名和常用邮箱比如 GitHub 上注册的用户名和邮箱。填写完成后Git 安装包会把这套信息写入~/.gitconfig后面我还会讲如何修改。2.2 “调整你的 PATH 环境变量”三种模式的区别安装进行到Adjusting your PATH environment这一步有三个单选选项选项作用建议Use Git from Git Bash only只能在 Git Bash 里使用 Git 命令不推荐你在 CMD、PowerShell、VSCode 终端里都调不到 GitGit from the command line and also from 3rd-party software把 Git 加入系统 PATH可以在 CMD、PowerShell 等任何终端中使用强烈推荐Use Git and optional Unix tools from the Command Prompt把 Git 自带的 Unix 工具也加入 PATH不推荐容易和 Windows 原有命令产生命名冲突我见过有人抱怨“Git 装好了PowerShell 里还是用不了”十有八九是选了第一个选项。要避免这个问题就选第二项。它会把git.exe所在目录加入系统 PATH之后无论是 CMD、PowerShell 还是 VSCode 内置终端都能直接敲git命令。2.3 换行符转换Windows 用户最需要理解的选项接着是Configuring the line ending conversions这个选项直接决定你是否会在 Git 操作中看到一堆warning: LF will be replaced by CRLF。这里需要理解两件事Windows 系统里文本文件换行用的是回车加换行CRLF即\r\n。Linux/macOS 系统里换行只用换行符LF即\n。Git 仓库内部默认采用 LF 来存储文本文件。如果 Windows 上的文件是 CRLF直接提交Git 会有两种处理策略提交前转成 LF检出时转回 CRLF或者干脆全部保持原样。安装向导提供三个选项Checkout Windows-style, commit Unix-style line endings签出时转成 CRLF提交时转成 LF。这是 Windows 用户的默认推荐项对绝大多数人的体验最友好。Checkout as-is, commit Unix-style line endings签出时保持仓库里的 LF不转 CRLF提交时转成 LF。Checkout as-is, commit as-is不进行任何转换。如果你主要是 Windows 单机开发选第一项就对了。如果你的团队有严格的跨平台代码规范后续可以通过git config core.autocrlf来精确控制安装时先按默认走。2.4 选择默认终端模拟器后面有一个选项叫Choosing the default terminal emulator让你选 Git Bash 使用的终端窗口Use MinTTYGit Bash 默认使用 MinTTY窗口外观更接近 Linux 终端支持富文本、快捷键更丰富。Use Windows default console window使用传统cmd风格的窗口。我的建议是保持默认的 MinTTY。它在处理vim、git log分页展示等场景下表现更好而且如果你后续在 VSCode 里把默认终端设成 Git Bash体验也会更接近 Linux 环境。安装最后还会询问是否启用实验性功能比如文件系统监视器、符号链接支持等。除了符号链接当前只有在开发者模式下才能启用其他实验功能一律不勾选求稳。3. 装完先不要急着建仓库把“三件套”环境配置好安装完成后打开 Git Bash先敲git --version确认能正常输出版本号。能正常输出说明 Git 已经成功进入 PATH。接下来要做的不是马上git init而是先把几个全局配置理清楚否则后面每一次提交都可能是带错误作者信息的脏数据。3.1 git config 的三个作用域Git 配置有三个层级理解它们之后很多“为什么配置不生效”的问题就迎刃而解系统级git config --system影响这台电脑上的所有用户配置文件在 Git 安装目录下的etc/gitconfig。全局级git config --global影响当前 Windows 用户配置文件在C:\Users\你的用户名\.gitconfig。仓库级git config --local只影响当前仓库配置文件在仓库内的.git/config。优先级从高到低是仓库级 全局级 系统级。也就是说仓库里单独设置的值会覆盖全局值。查看当前生效的配置用git config --list --show-origin它会明确告诉你每条配置来自哪个文件和哪一行。3.2 必备配置名字、邮箱、默认分支名、编辑器安装界面虽然让你填过用户名和邮箱但用git config命令显式配置依然有意义。因为你可能中途改主意也可能安装时图省事填了错误信息。推荐在 Git Bash 里执行以下命令git config --global user.name 你的用户名 git config --global user.email 你的邮箱注意用户名和邮箱务必和远程仓库平台GitHub/Gitee/GitLab的账号信息对应上这样每次提交都能正确关联到你的账号头像。接下来设置默认分支名。以前 Git 自动创建的分支名是master现在越来越多的平台默认用main。为了避免每次git init之后还要手动改分支名直接设置成你习惯的名称git config --global init.defaultBranch main编辑器这里也建议设一下。如果你不设Git 在需要你输入提交信息时会调默认的vim。对不熟悉 vim 的人来说进入编辑界面后就不知道按什么键退出非常痛苦。你可以设置成 VSCodegit config --global core.editor code --wait设置完成后再执行git config --list --global检查所有全局配置是否都在。这一步看起来简单但这是整个 Git 使用生涯的地基。3.3 推荐进阶配置换行符控制、别名与界面优化基础三件套配好之后再补几个能显著提升体验的配置。首先是换行符。如果安装时选了“签出 CRLF、提交 LF”那么core.autocrlf默认已经是true一般情况下不需要改动。但如果你发现仓库里出现了换行符相关的警告或者团队里有人是 Linux 环境建议再显式配置一次git config --global core.autocrlf true git config --global core.safecrlf truesafecrlf的作用是在发生不可逆的换行符转换时给出警告。举个例子仓库里有个二进制文件被误识别为文本文件进行 CRLF/LF 转换时就可能损坏内容safecrlf会提前提醒你。然后是别名。Git 命令本身不算短配置常用别名能提高效率git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.lg log --oneline --graph --all --decorate配置完成后输入git st等同于git status输入git lg可以查看图形化的提交历史。最后可以开启颜色显示git config --global color.ui true这个配置让git status、git diff等命令的输出带上颜色区分度明显提升。4. SSH 密钥从生成到上线的完整链路环境配置完成后紧接着要解决的是“怎么验证身份、怎么连接远程仓库”。本地写代码不需要身份验证但一旦要git push到 GitHub、Gitee、GitLab 这些远程平台就必须证明“你是你”。常见的验证方式有两种HTTPS 加个人访问令牌Personal Access Token以及 SSH 密钥认证。SSH 密钥是很多人的首选因为配置好之后不需要反复输入密码安全性也很高。4.1 为什么建议优先用 SSH 而不是 HTTPS用 HTTPS 连接远程仓库传统做法是每次 push 都要输入用户名和密码。后来平台普遍改用个人访问令牌代替密码但令牌有有效期过期之后又要在网页端重新生成很是繁琐。SSH 密钥的机制不同本地保存一把私钥远程平台保存一把公钥。发起连接时Git 用本地私钥对数据进行签名远程平台用公钥验证。整个过程不传输密码私钥也只在本地。只要配置得当一次配置之后长期可用这是它最大的优势。4.2 生成密钥前先看看是否已经有旧密钥很多人在生成密钥时会踩一个坑明明执行了ssh-keygen但在平台添加公钥时却发现连接仍然失败。原因很可能是在生成密钥时命令提示“已存在同名文件”而自己没仔细看直接覆盖了旧的密钥导致原来配置好的平台连接全部失效。所以在生成之前建议先列出已有的密钥文件ls -la ~/.ssh/输入ls时要注意~在 Git Bash 中指的是当前用户目录即C:\Users\你的用户名。如果目录里已经存在id_ed25519、id_rsa这类文件说明你以前生成过密钥。可以先用下面的命令测试它能否连接 GitHubssh -T gitgithub.com如果返回Hi 用户名! Youve successfully authenticated说明旧密钥还能用那就没必要重复生成。如果返回的是权限错误再决定是修复旧密钥还是重新生成。4.3 用 ssh-keygen 生成密钥参数与步骤详解生成密钥的命令很简单为什么推荐用 ed25519 算法而不是传统的 RSA因为 ed25519 密钥更短、生成速度更快、安全性在当前场景下已经足够而且 GitHub、Gitee 都支持。注意同一个远程平台不建议重复添加多把公钥如果你不太确定以前生成过什么建议先把~/.ssh目录内容看清楚再操作。在 Git Bash 中执行ssh-keygen -t ed25519 -C 你的邮箱这里-C后面的内容只是注释方便你以后识别这把密钥属于哪台设备填写自己的邮箱最直观。执行后会出现提示Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):推荐直接按回车使用默认路径。如果输入自定义路径后续配置要额外修改 SSH config徒增复杂度。接着会要求设置 passphraseEnter passphrase (empty for no passphrase):这里的意思是给私钥加一层密码保护。如果你设置了 passphrase每次使用私钥连接远程仓库时都需要输入它。如果你觉得麻烦可以直接留空。但如果这台电脑可能被别人使用或者是一台笔记本我强烈建议设置 passphrase。结合后面的ssh-agent你只需要在会话开始时输入一次后面就不需要重复输入了。生成完成后~/.ssh目录下会出现两个核心文件id_ed25519私钥相当于你的“身份证原件”绝对不能泄露、不能上传到任何网站、不能发给任何人。id_ed25519.pub公钥可以公开需要添加到远程仓库平台。cat ~/.ssh/id_ed25519.pub输出的内容是ssh-ed25519 一串长字符串 你的邮箱主机名的格式。复制这份完整内容后续要用。4.4 ssh-agent把私钥“记住”省去反复输入 passphrase如果你设置了 passphrase又不希望每次操作都输入一次那就需要启动ssh-agent服务。它的作用是把你的私钥加载到内存中后续 Git 操作自动调用不再重复询问密码。在 Git Bash 中执行eval $(ssh-agent -s)这条命令的意思是先启动 ssh-agent 后台服务然后把它的环境变量导入当前终端。输出往往是一串数字表示进程 ID。接着把私钥加入 agentssh-add ~/.ssh/id_ed25519如果之前设置了 passphrase此时会要求输入一次之后在当前终端会话里就无需再次输入。需要注意ssh-agent的“记忆”作用范围是当前会话关闭终端后重新打开通常需要再次执行上述两条命令。如果觉得麻烦可以把这两条命令写入~/.bashrc文件让 Git Bash 每次启动时自动执行。编辑~/.bashrceval $(ssh-agent -s) /dev/null ssh-add ~/.ssh/id_ed25519 /dev/null 21注意第二种写法里的 /dev/null只是为了屏蔽无关输出实际使用中可以根据自己的喜好决定是否保留提示信息。4.5 把公钥添加到 GitHub 和 Gitee以 GitHub 为例登录 GitHub 网页端进入Settings设置左侧找到SSH and GPG keysSSH 和 GPG 密钥点击New SSH key新建 SSH 密钥把刚才复制的公钥内容粘贴进去标题可以写“Windows 笔记本”“公司电脑”之类的标识方便以后区分设备。保存后公钥就完成了绑定。Gitee 的操作路径类似进入个人设置找到“安全设置—SSH 公钥”粘贴公钥内容保存即可。添加公钥的瞬间你可能会看到 GitHub 向注册邮箱发送一封确认邮件提示 SSH key 已添加。这说明公钥已经生效。4.6 测试连接确认整条链路是否打通添加完成后回到 Git Bash执行ssh -T gitgithub.com如果是第一次连接系统会提示无法确认主机真实性The authenticity of host github.com (140.82.114.4) cant be established. Are you sure you want to continue connecting (yes/no)?这是正常的指纹确认提示输入yes回车即可。这一步会把 GitHub 的主机指纹记录到本机的~/.ssh/known_hosts文件中之后不再重复询问。如果一切正常稍等片刻会返回类似这样的输出Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.看到这句话就说明 SSH 链路已经完全打通。同样测试 Giteessh -T gitgitee.com返回类似Hi 你的用户名! Youve successfully authenticated的输出即为成功。这里有个小提醒Gitee 的成功提示里同样会强调“does not provide shell access”这很正常因为 SSH 只是为了 Git 操作服务本就不提供远程命令行环境。5. 多平台多个密钥的管理一个 config 文件说得清很多人手里不止一个代码托管平台可能 GitHub 上放开源项目Gitee 上放国内仓库公司内部还部署了一套 GitLab。如果每个平台都用同一把密钥理论上没有问题但如果你希望不同平台用不同邮箱、不同密钥就需要借助 SSH config 文件来管理。5.1 先在 .ssh 目录下把多把密钥生成出来通过前文的办法分别生成不同平台的密钥。例如先按默认路径生成id_ed25519给 GitHub再生成第二把时指定不同文件名ssh-keygen -t ed25519 -C giteeexample.com -f ~/.ssh/id_ed25519_gitee-f参数指定输出文件名。此时~/.ssh下就有了两套密钥。分别用cat查看各自的公钥内容添加到对应平台。5.2 编写 config 文件实现域名与密钥的自动对应在~/.ssh目录下新建一个文件命名为config注意没有扩展名。用编辑器写入以下内容# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 # Gitee Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee配置文件的含义很直观Host是你在命令行中使用的别名HostName是真实域名IdentityFile是对应使用的私钥路径。配置完成后重新测试两个平台的连接ssh -T gitgithub.com ssh -T gitgitee.com两条命令会自动使用不同的私钥互不干扰。这里的User git表示托管平台的 SSH 用户统一为git这是平台规则不用修改。5.3 配置文件不起作用的常见原因有几次我帮同事排查 SSH 连接问题明明 config 文件写得很规范但命令还是提示找不到对应私钥。后来发现原因出在文件权限上。Windows 下虽然不像 Linux 那样严格要求私钥权限但如果你开启了 OpenSSH 服务某些情况下也会校验权限。在 Git Bash 中可以通过ls -l ~/.ssh查看权限正常情况下私钥权限应该是-rw-------也就是只有当前用户可读写。如果不小心用某些同步工具把整个用户目录同步到多台电脑也要注意~/.ssh目录不要轻易直接复制到另一台机器因为每台机器的私钥独立生成更有安全性。另一个常见问题是配置文件名。Windows 资源管理器下新建文本文件会默认叫config.txtGit 读取的是config导致配置不生效。在 Git Bash 里创建配置可以使用touch ~/.ssh/config然后用notepad ~/.ssh/config或 VSCode 打开编辑就不会有扩展名问题。6. 高频报错现场我把踩过的坑按错误信息整理好了配置过程一路走下来几乎每个阶段都有对应的报错。下面把最常遇到的几类问题整理成对照表并给出排查链路和解决方法。6.1 git 不是内部或外部命令这个报错几乎都出在 PATH 环境变量未配置或配置未生效。如果你安装时选择了Use Git from Git Bash only那么 CMD 和 PowerShell 自然无法识别 git 命令。解决办法是重新运行安装程序修改 PATH 选项或者在系统环境变量里手动把 Git 的cmd目录加入 PATH。注意修改环境变量后需要重新打开终端窗口才会生效。如果发现新终端仍然报错可以执行where git检查系统实际找到了哪个 git。有时候系统里有多个版本的 Git优先匹配到旧的导致行为异常。6.2 Permission denied (publickey)这是 SSH 密钥配置最常见的问题。报错的完整形式一般是gitgithub.com: Permission denied (publickey).排查链路按照优先级排列检查本地能否访问到私钥文件ls -l ~/.ssh/id_ed25519如果文件不存在说明密钥没生成成功或路径不对。检查 ssh-agent 是否加载了私钥ssh-add -l如果显示The agent has no identities先执行前面提到的eval $(ssh-agent -s)和ssh-add ~/.ssh/id_ed25519。检查公钥是否已添加到平台。重新执行cat ~/.ssh/id_ed25519.pub复制内容去平台后台核对粘贴过程中不要多出空格或换行。检查连接时用的是哪把密钥。如果配置了多把密钥且没有 config 文件指定SSH 会默认尝试id_ed25519。如果该密钥不是绑定目标平台的密钥就会报错。这时写一个明确的 config 文件就能解决。6.3 SSL certificate problem执行 Git 操作时报 SSL 证书相关的错误大多是系统里安装了代理或网络环境导致证书链不完整。这个报错我不能给出“绕过证书校验”的建议因为那样会削弱安全性。正确的做法是保持证书校验开启并确保系统时间正确、证书库完整。如果你使用的是公司内网仓库且自签了证书需要让管理员把证书正确安装到系统受信任的根证书目录而不是在 Git 里关闭校验。6.4 中文乱码问题Git 在 Windows 下显示中文文件名或中文提交信息时可能出现乱码。核心原因是编码方式不一致。Windows 默认的代码页是 GBK而 Git 内部使用 UTF-8。解决办法是让 Git 强制使用 UTF-8 输出git config --global core.quotepath false git config --global gui.encoding utf-8 git config --global i18n.commit.encoding utf-8 git config --global i18n.logoutputencoding utf-8同时建议把 Git Bash 终端编码也设为 UTF-8。在 Git Bash 窗口标题栏右键选择“选项—文本”把本地编码改为 UTF-8 即可。这组配置主要影响显示层仓库内部的存储标准保持 UTF-8 不动兼容性最好。6.5 warning: LF will be replaced by CRLF这不是错误而是提示。它出现在你提交的文件中包含 LF 换行符而 Git 的core.autocrlf设置为true时Git 会在下次签出时自动转换成 CRLF。一般情况下不用处理。但如果仓库里包含大量二进制或混合换行符的文件建议检查.gitattributes文件把特定类型的文件按照规则明确指定换行符行为而不是依赖全局配置。比如*.sh text eollf *.bat text eolcrlf这样每个文件类型使用什么换行符仓库内就能做到有据可查。7. 把 Git 用顺手写代码时的日常操作与工具联动走到这一步Git 本身已经装好、配置好、SSH 也通了。接下来聊一聊日常开发时 Git 怎么和编辑器配合以及我最常用的一套命令组合。7.1 让 VSCode 使用 Git Bash 作为默认终端VSCode 是 Windows 用户最常用的编辑器之一它的内置终端默认是 PowerShell。虽然 PowerShell 里也能运行 Git 命令但如果你已经习惯 Git Bash 的环境建议把默认终端改成 Git Bash。打开 VSCode按Ctrl Shift P打开命令面板输入Terminal: Select Default Profile在列表中选择Git Bash。之后每次打开集成终端进入的就是 Git Bash 环境。这样无论是git status还是ssh -T gitgithub.com操作体验和独立窗口完全一致。7.2 VSCode 源代码管理面板背后做了什么很多新手习惯只点 VSCode 左侧的“源代码管理”图标进行提交、推送点完却不清楚背后发生了什么。这里做一个对应关系梳理VSCode 界面操作对应 Git 命令含义点击“更改”列表git status查看工作区状态点击“”号git add file把文件加入暂存区输入提交信息并点击“提交”git commit -m message创建一次提交点击“同步更改”git pushgit pull先拉取远程更新再推送本地提交点击“分支”按钮git branch/git checkout切换或创建分支理解这层对应关系后在 VSCode 里操作时就不会有“玄学”感了。如果某个按钮点了没反应回到终端手动执行对应命令错误信息会立刻显示出来排查更高效。7.3 日常高频命令组合最后分享一组我每天都会用到的命令。它们不复杂但组合起来能覆盖大多数开发场景# 当前仓库状态建议每次操作前先看一眼 git status # 把某个文件加入暂存区或一次性把所有改动加入暂存区 git add path/to/file git add -A # 提交并写清楚改了啥 git commit -m fix: 修复登录接口超时问题 # 推送当前分支到远程同名分支 git push # 拉取远程更新并保持提交历史整洁 git pull --rebase # 看提交历史一行一提交带分支图 git log --oneline --graph --all --decorate # 比对我对某文件做了什么改动 git diff path/to/file还有一个非常实用但经常被新手忽略的命令是git stash。当你正在 A 分支改代码突然需要切到 B 分支处理紧急问题但改动还没完成、不想提交这时执行git stash它会把当前工作区的改动暂存起来工作区恢复到干净状态。处理完 B 分支的事再切回 A 分支执行git stash pop改动就回来了。这个操作很像把你的桌面临时整理进抽屉事情做完再拿出来不会丢失任何东西。我个人在实际操作中的一点体会是Git 这套工具链里最容易出问题的往往不是命令本身而是 Windows 环境下的各种隐含配置——PATH、换行符、密钥权限、终端编码。你花一整个下午把每一步都验证一遍后面使用起来会非常顺畅。尤其是 SSH 密钥第一次跑通之后你会发现git clone、git push都变成了一件“毫无存在感”的事代码就在本地和远程之间安静地流转。这种顺畅感值得你花时间把整套环境配好。