距离上次重装系统已经过去大半年这几天换了台新电脑光是折腾 Git 环境就花了我一个下午。倒不是说 Git 安装有多难而是下载、安装、环境变量、SSH 密钥这一整套流程分散在好几篇教程里版本新旧不一照着敲还容易踩坑。Windows 上的 Git 配置确实有点碎但把它们串起来看其实就是一个标准流水线。这篇教程我把整个流程完整走了一遍从下载安装包开始到安装选项逐项解释再到环境变量配置、换行符设置、SSH 密钥生成与添加最后到多平台密钥管理和常见问题排查。不论你是刚接触 Git 的新手还是被各种报错折磨的老朋友照着这篇文章操作基本能一次性把环境搞定。我尽量把每一步“为什么要这么选”也讲清楚这样你以后遇到类似问题自己也能判断该怎么处理。1. 整体安装思路先把“准备做足”再做“配置”很多人安装 Git 的习惯是双击 exe、一路 Next、装完打开 Git Bash 就开始敲命令。大多数情况下是能用的但等你 push 代码到 GitHub、Gitee 或者公司 GitLab 时问题就来了——要么仓库地址输进去提示权限不足要么每次操作都要输密码要么中文文件名乱码。这些问题根子都在安装时的选项没选对或者 SSH 密钥压根没配。1.1 为什么建议走“完整配置路线”而不是“默认一路下一步”Git 安装包的设计确实考虑了“开箱即用”默认选项如果往后不管日常练习 clone 公开仓库、本地提交是完全没问题的。但它默认带的编辑器是 Vim、默认的换行符处理规则靠自动判断、默认不创建桌面快捷方式这些对于新手来说并不友好。尤其是换行符如果不管Windows 和 Linux/macOS 协作时很容易出现“明明没改过的文件git diff 里却显示整文件变了”的诡异现象。所以我的建议是第一次安装就花两分钟把几个关键选项选对后面能帮你省掉一大串麻烦。这篇教程的安装部分就不只是给你“下一步下一步”的流程而是每个关键选项都会解释一下它影响什么。关于 SSH 密钥我建议直接生成哪怕你现在只玩本地仓库后面只要涉及到远程仓库就一定会用到。早配早省心。1.2 准备清单先确认这三样东西开始操作之前你先确认一下一个稳定的网络环境。下载安装包需要联网后面用 GitHub 也需要联网。一个邮箱地址。Git 的每次提交都会记录提交者信息推荐用你注册 GitHub/Gitee 的邮箱这样提交记录能正确关联到你的账号头像。一个自己能记住的密码。SSH 密钥生成时可以设置口令passphrase后面用到私钥时需要输入。这个不急可以先不设但如果你所在环境对安全要求高建议设置。另外如果你电脑上已经装了旧版 Git比如 2.3x 版本建议先卸载旧版再装新版。不过实测下来高版本 Git 直接覆盖安装也可以配置文件一般不会丢只是个别安装选项会覆盖稳妥起见还是先卸载干净。2. 下载与安装逐项拆解安装向导Git 官网的下载页面有时候加载比较慢这是正常现象。我一般是直接访问 git-scm.com/download/win选择 64-bit 版本。如果你不确定系统是 32 位还是 64 位右键“此电脑” - “属性”看“系统类型”那栏就知道了。现在基本都是 64 位系统除非是特别老的机器。2.1 安装向导关键选项怎么选拿到安装包后双击运行看到许可证页面直接 Next。真正需要关注的从 Select Components 开始安装选项建议选择说明附加图标按需勾选额外图标建议不创建直接搜 Git Bash 更方便默认编辑器建议选 Visual Studio Code如果没有 VS Code选 Notepad 或 Vim 也行但 VS Code 和 Git 配合最舒适PATH 环境变量推荐中间项Git from the command line...这样 CMD、PowerShell 里也能直接用 git 命令HTTPS 传输后端默认 OpenSSL 即可如果公司网络有特殊要求自己有证书那再换行结束符处理推荐第一项Checkout as-is, commit as-is不自动转换换行符最省心终端模拟器选 MinTTY比 Windows 自带终端更好用默认 pull 行为选默认 (fast-forward or merge)维护成本最低credential helper选 Git Credential Manager以后首次输入账号密码后会自动记住这里有两个选项值得单独展开讲讲。PATH 环境变量那一页很多教程直接让你选中间项但没有解释为什么。如果选了第一项“仅从 Git Bash 使用 Git”那你在 CMD 或 PowerShell 里敲 git 就会提示“不是内部或外部命令”。虽然你可以手动把路径加到环境变量里但既然安装包提供了这个选项直接用就好。选了它之后git.exe 会被加到系统 PATH 中CMD、PowerShell、Windows Terminal 里都能直接运行 git 命令。换行符处理这个非常关键。Unix 系统Linux、macOS用 LF\n作为换行符Windows 用 CRLF\r\n。Git 默认会帮你把仓库里的 LF 转成 CRLF 检出到本地提交时再转回 LF。听起来很智能但如果你团队里恰好有人写脚本处理文本内容这种隐式转换会带来各种奇怪的 bug。所以我推荐选择“Checkout as-is, commit as-is”也就是关闭自动转换。这么做的代价是如果你用 Windows 自带记事本打开某些从仓库检出的文件行尾可能不统一但现代编辑器VS Code、Sublime、Notepad都能正常处理完全不是问题。2.2 安装完成先别急着用做这三步验证安装完成后先不要急着 clone 仓库。我习惯先做三个快速验证确认 Git 环境是正常的。第一步打开 Git Bash开始菜单搜索 Git Bash输入git --version能输出类似git version 2.4x.x.windows.1就说明安装成功。第二步确认 git 命令在 CMD 里也能用。按Win R输入 cmd回车在黑窗口里敲同样的命令git --version如果提示“不是内部或外部命令”说明 PATH 没有生效。可以先试着重开一个 CMD 窗口还不行就手动检查环境变量。第三步打开 Git GUI 或直接运行git help确认帮助文档正常加载。这步不是必须的但能确认安装文件没有损坏。如果你安装时选了 Git Credential Manager首次执行涉及远程仓库的操作时系统会弹出登录窗口让你输入平台账号密码。这是正常的输一次就会记住。注意Git Credential Manager 默认存储的是普通凭据不是 SSH 私钥。后面配置好 SSH 密钥后建议在 clone 仓库时使用 SSH 协议的地址gitgithub.com:user/repo.git这样才会走密钥认证。3. 环境配置让 Git 在你的终端里按你的习惯工作安装只解决了“有没有”的问题要让它好用还得做一层环境配置。这层配置不复杂但很容易被漏掉或者因为搞不清该用哪条命令而放弃。其实企业里 Git 用得利索的人配置文件大概率就那么几行。3.1 全局用户信息提交记录的“署名”安装完成后第一次提交代码前Git 会要求你配置用户名和邮箱。如果不配置push 时会报错提示缺少 user name 和 user email。打开 Git Bash依次输入git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的“你的名字”建议用你自己习惯的英文 ID后续所有提交记录里都会显示这个名字。邮箱建议用注册 GitHub/Gitee 的邮箱这样提交记录能正确关联到账号。你可以用以下命令验证是否配置成功git config --global --list会输出 user.name、user.email 等条目说明配置已经生效。配置文件的位置在用户主目录下的.gitconfig你随时可以用文本编辑器去查看和修改。有一些教程会让你顺手配置git config --global init.defaultBranch main把默认分支名从 master 改成 main。这个看个人习惯如果你和团队都用 main 分支那建议也加上git config --global init.defaultBranch main好处是以后执行git init时初始分支直接是 main少一步分支重命名操作。3.2 换行符与编码设置跨平台协作不闹心换行符问题值得多说两句。如果你团队只有 Windows 成员或只有 macOS/Linux 成员那问题不大。但如果混合协作换行符设置不合适就等着被无意义 diff 折磨吧。前面安装时建议选了“Checkout as-is, commit as-is”对应的配置是git config --global core.autocrlf false这个配置会告诉 Git不要擅自转换换行符。仓库里存什么行尾检出来就是什么行尾。假如你要把一个 Linux 服务器上管理过的仓库 clone 到 Windows检出来的文件行尾是 LF用记事本打开看起来可能没有自动换行但现代编辑器都能识别不影响编辑和保存。如果你习惯 VS Code 或 Sublime 这类编辑器我建议直接在编辑器里配置“默认行尾符为 LF”或“detect from content”这样基本能做到无感。中文乱码也属于编码问题。Windows 上 Git Bash 偶尔会出现中文文件名显示成\346\265\213\350\257\225.txt这类八进制转义序列或者在 log 里看到中文乱码。处理方法是在 Git Bash 里执行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-8core.quotepath false这个配置最实用它让 Git 直接显示中文文件名不再转义。后面几个配置则是确保提交信息和 log 输出都按 UTF-8 处理。Windows 系统默认代码页可能不是 UTF-8但 Git for Windows 的 MinTTY 终端对 UTF-8 的支持还不错配置好之后基本不会乱码。3.3 初始化仓库与首次提交验证环境配置是否真能用配置做完建议立刻初始化一个本地仓库走一遍完整提交流程确保后续实操时不会有环境问题。我这边的具体操作记录如下mkdir demo-git cd demo-git git init echo # Hello Git README.md git add README.md git commit -m first commit执行到git commit时如果前面用户信息没配置Git 会直接把错误甩你脸上提示Please tell me who you are并告诉你该执行哪两条命令。这条报错信息本身就相当于一个引导照着做就行但提前配置好会省事很多。提交完成后执行git log --oneline能看到类似abc1234 first commit的输出说明 Git 环境的读写、提交、日志输出全部正常。到这里本机 Git 环境已经可以正常使用了。如果你还需要和远程仓库GitHub、Gitee、GitLab交互那紧接着做 SSH 密钥的生成与配置。4. SSH 密钥生成与配置从生成到免密登录SSH 密钥听起来挺高大上但它本质上就是一对文件一个公钥一个私钥。公钥放到代码托管平台上相当于一把锁私钥留在本机相当于钥匙。每次 Git 通过 SSH 协议连接远程仓库时服务端用公钥验证你的身份验证通过就放行。这样你就不必每次 push 都输用户名密码。4.1 生成密钥的具体步骤打开 Git Bash执行ssh-keygen -t ed25519 -C 你的邮箱这里选 ed25519 是因为它比传统的 RSA 密钥更安全、更短而且现代代码托管平台都支持。如果你的 Git 版本比较老2.3x 之前或者要连接的公司 GitLab 版本比较老可能不支持 ed25519那就用 RSAssh-keygen -t rsa -b 4096 -C 你的邮箱执行后会提示你设置保存路径默认是/c/Users/你的用户名/.ssh/id_ed25519直接回车使用默认路径即可。接着会提示你输入 passphrase这相当于给私钥再加一道口令保护。如果你希望每次使用私钥时都输入密码就设置一个嫌麻烦就留空直接回车。我个人的做法是本地开发环境留空公司电脑设置 passphrase防止电脑丢失后私钥泄露。生成完成后进入.ssh目录cd ~/.ssh ls正常情况下能看到两个文件id_ed25519私钥和id_ed25519.pub公钥。私钥绝对不能泄露给任何人公钥可以放心发给代码托管平台。4.2 查看公钥并配置到代码托管平台查看公钥内容cat ~/.ssh/id_ed25519.pub输出是一行以ssh-ed25519开头的长字符串。把这整行内容复制下来。以 GitHub 为例登录后进入Settings - SSH and GPG keys - New SSH keyTitle 随便填比如“我的Windows电脑”Key 粘贴刚才复制的内容点 Add SSH key。Gitee 的操作路径是设置 - SSH公钥GitLab 是用户设置 - SSH 密钥基本逻辑一样。4.3 测试连接证明密钥没白配配置完后在 Git Bash 里测试一下ssh -T gitgithub.com如果看到类似Hi yourname! Youve successfully authenticated, but GitHub does not provide shell access.的输出就说明 SSH 密钥已经生效Git 可以免密访问 GitHub 了。这里有个细节要说清楚使用 SSH 协议 clone 仓库时地址格式是gitgithub.com:用户名/仓库名.git不是https://github.com/用户名/仓库名.git。很多人密钥半天配不起来结果是 clone 时用的还是 HTTPS 地址自然会不断要求输入密码。你可以在仓库页面点击 Code 按钮选择 SSH 标签页复制 SSH 格式的地址。4.4 多个代码平台的多密钥管理有同学既用 GitHub 又用 Gitee甚至还有公司内部的 GitLab三套账号三套密钥怎么处理最简单粗暴的方法是生成多个密钥对然后靠~/.ssh/config文件来区分。举个例子ssh-keygen -t ed25519 -C github邮箱 -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C gitee邮箱 -f ~/.ssh/id_ed25519_gitee这样会生成两组不同的公钥和私钥。然后在~/.ssh目录下新建一个名为config的文件注意没有扩展名写入Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee保存后Git 就会根据你访问的域名自动选择对应的私钥。这样 GitHub 和 Gitee 都能免密访问互不干扰。这个配置文件同样适用于公司 GitLab只要把 Host 改成你公司 GitLab 的域名即可。我第一次用这个方案的时候踩过一个坑Git Bash 在新建 config 文件时会自动加.txt后缀导致配置文件没被识别连接一直报错。后来我在 Git Bash 用touch config创建纯文本文件路径才正确。如果你用 Windows 资源管理器右键新建注意把文件名改成config不要保留.txt。5. 常见问题与排查我踩过一遍的坑大汇总教程写到这基本流程已经完整了。但我知道你实际操作时大概率会遇到下面这些报错之一二这些是我这些年真实踩过的坑整理成速查表方便遇到问题直接对照。报错信息可能原因解决办法Permission denied (publickey)公钥没配到平台或 Git 用了错误的密钥检查ssh -T gitgithub.com输出确认公钥已粘贴到平台检查.ssh/config配置Host key verification failed首次连接远程服务器本地没有对方主机指纹记录输入yes确认继续连接如果提示密钥不匹配检查是否配置了错误的HostNamefatal: not a git repository当前目录不是 Git 仓库先cd到含.git目录的路径或执行git init初始化每次 push 都要输用户名密码使用了 HTTPS 协议且配置未保存凭据改用 SSH 协议 clone或确认 Git Credential Manager 已生效中文文件名显示成数字转义Git 默认对非 ASCII 文件名进行转义执行git config --global core.quotepath false提交信息中的中文乱码终端编码与服务端不一致配置i18n.commit.encoding和i18n.logoutputencoding为 utf-8确认终端字体支持中文LF will be replaced by CRLF 警告检测到换行符差异Git 尝试自动转换如果你已设置core.autocrlf false可忽略否则根据团队规范统一换行符策略403 或前端显示 failed to authenticate平台 Token 失效或 GitLab 版本兼容问题重新生成 Token或在支持范围内选用 SSH 方式认证5.1 Permission denied 的排查边界SSH 连不上时我习惯按顺序排查三步。第一步看本地是否持有私钥执行ls -la ~/.ssh第二步看密钥 agent 是否在运行如果ssh-add -l报错执行eval $(ssh-agent -s)再ssh-add第三步看公钥是否已加入平台且和本机私钥匹配这个过程把本机公钥内容与平台记录逐个字符比对一下很容易发现是粘贴时漏了字符。还有一种是公司 GitLab 场景下如果登录时提示login failed. check api token or gitlab version这通常是 Git 客户端或 IDE 集成插件使用 API Token 认证失败先把本地缓存的凭据清掉重新用浏览器授权登录一次。如果 GitLab 版本很老记得检查它是否支持你当前 Git 客户端的认证方式。5.2 换行符警告值的处理思路第一次用 Git 拉代码时很多人会被warning: LF will be replaced by CRLF这类输出吓到。这个提示其实只是告知你 Git 的换行符转换策略正在生效不一定是错误。关键是全团队约定统一。如果你按前文建议设置了core.autocrlf false检出和提交都按原样处理就不会有这种警告。如果你所在团队是 Windows 为主大家统一用 CRLF 也没问题设置core.autocrlf true即可。最怕的是今天这个成员用 true明天那个成员用 falsediff 满天飞。5.3 仓库地址用错导致的免密失败还有一种常见的免密失败是 clone 地址选错。如果复制的是 HTTPS 地址那你配置的 SSH 密钥根本不会参与认证Git 会一直要求你输入账号密码。这本不算 bug但很多人会把它当成“SSH 密钥没配置成功”。结论是使用 SSH 免密就一定要用 SSH 协议地址。仓库页面 Code 下拉框里默认展示 HTTPS记得切换标签再到 SSH 页签复制。5.4 我的 Git 环境备份恢复习惯环境配置好以后建议把这些配置项沉淀成一个脚本或记录到自己的笔记系统里。我自己的.gitconfig内容其实是固定的换新电脑时只需要复制过去改一下 user.name 和 user.email 就能恢复。.ssh/config也建议直接备份配合私钥和公钥文件换电脑半小时内就能恢复到和生产环境一致的 Git 工作环境。这个小习惯帮我省过两次大麻烦一次是电脑突然报废一次是公司要求换发新笔记本。我只需要把.gitconfig、.ssh目录整体拷过去或者用自己搭建的私有仓库同步然后执行ssh-add把私钥加入 agent新环境立刻可用。如果你有更精细的管理需求也可以把这些配置统一放到 dotfiles 仓库里管理Git 本身就是一个顺手的配置同步工具。我个人的体会是Git 环境的稳定运行一半靠安装配置正确另一半靠平时的使用习惯。SSH 密钥生成完最好做一次备份放到加密的 U 盘或者密码管理器里日常使用中留意 Git Bash 里的警告信息不要一看到英文提示就直接忽略每隔一段时间用git config --global --list检查自己的配置及时发现异常项。这样一套操作下来你的 Git 环境不敢说绝对不出问题但遇到问题的概率会低很多。后面如果你们团队需要上 CI/CD这套配置好的 SSH 密钥还能直接复用到服务器上算是提前打好底子。