Git 是每个开发者都绕不开的版本控制工具尤其在 Windows 上很多人装完 Git 就以为万事大吉结果一提交代码就报错一推送仓库就要求输密码折腾半天才发现“安装”和“环境配置”完全是两件事。这篇保姆级教程我会从 Git 下载、安装、环境配置一直讲到 SSH 密钥的生成与关联把 Windows 环境下从零到能正常推拉代码的整个过程完整走一遍。刚入行的新手可以直接照做已经用了很久 Git 但一直没把配置理顺的同学也能在这里查漏补缺。在实际帮人排错的过程中我发现大部分人卡住的点不在于 Git 命令本身而在于 Windows 和 SSH 之间的这套链路没有打通PATH 没选对终端里敲 git 命令系统根本不认识用户信息没配好提交记录一片混乱SSH 密钥没搞懂每次推送都要输密码。这篇文章不光是步骤讲解我会把每一步背后的原因也说明白这样以后再遇到类似问题至少知道该往哪个方向排查而不是把整个环境重装一遍。1. 安装之前先搞懂Git、仓库与 SSH 各自扮演什么角色1.1 为什么说“装了 Git”不等于“配置好了”Git 官方为 Windows 用户提供了 Git for Windows 安装包它实际上是一套在 Windows 上编译好的 Git 命令行工具外加一个名为 Git Bash 的模拟环境。很多新手装完之后直接在开始菜单里打开 Git Bash敲一个git --version看到版本号输出就觉得自己会用了。但真正开始开发工作时两个最常见的阻碍马上就会出现。第一个阻碍是 Git 不知道你是谁。每次执行git commitGit 都会把作者信息写入提交记录如果环境里没有配置用户名和邮箱它就无法确定提交人于是直接拒绝提交并抛出 Please tell me who you are 错误。注意这个信息和你代码托管平台注册的账号没有强制绑定它只是提交记录里的文本字段但团队协作时全靠它来区分“谁改了这一行代码”。第二个阻碍是远程仓库不信任你的电脑。无论你用 GitHub、Gitee 还是公司自建的 GitLab远程仓库都不会凭白允许你推送代码。主流验证方式有两种一种是 HTTPS 协议每次推送时输入账号密码或访问令牌另一种是 SSH 协议通过本地生成的一对公私钥完成身份验证。很多人卡在这一步并不是因为操作有多难而是没搞懂“公钥交给服务器、私钥留在本机”这套逻辑。1.2 SSH 和 HTTPS 两种连接方式怎么选在正式开始安装前建议你先想清楚一个问题后面打算用哪种方式连接远程仓库如果选 HTTPS配置成本确实更低但代价是每次 push/pull 都可能要求你提供凭据。就算用了 Git Credential Manager 帮你记住账号密码也只是把问题延后并不优雅。如果选 SSH只需要生成一次密钥、把公钥放到代码托管平台之后就不再需要反复输入账号密码。对于频繁推送代码、同时维护多个仓库的开发者来说SSH 是明显更省心的选择。在这篇教程里我会把 SSH 密钥的完整流程讲透。至于 HTTPS我会在环境配置部分提一下 Credential Manager 的作用方便你根据自己的实际场景做取舍。先说明这一点可以让你在跟着教程操作时心里更有数而不是机械地照搬命令。2. Windows 下 Git 的下载与安装全程拆解2.1 下载地址和版本选择Git 的官方下载地址是 git-scm.com进入首页后它会自动检测当前系统并显示 Windows 版本的下载按钮。如果你想手动选择安装包可以进入 Downloads 菜单下的 Windows 页面里面列出了 32-bit 和 64-bit 两种架构的独立安装包也有 Portable 便携版。这里有两个细节值得注意。第一个是电脑架构现在的电脑绝大多数都是 64 位直接选 64-bit 即可如果你不确定可以在“设置 系统 关于”里查看“系统类型”。第二个是版本选择Git 的版本号迭代很快对日常使用来说没必要追新选官方首页推荐的稳定版就行。但如果你所在的团队对 Git 版本有硬性要求也可以在版本归档页里找到对应版本下载。下载过程中最让人头疼的通常是速度问题。这里我不推荐任何花哨的加速手段只给一个很实用的思路如果官网下载速度不理想可以换用高校镜像站或云厂商的开源镜像站很多镜像源都同步了 Git for Windows 安装包挑一个离你更近的镜像下载会快不少。安装包通常只有几十 MB下载完双击运行即可。2.2 安装向导中的关键选项Git 安装向导整体上是“下一步”式的流程但中间有几步非常关键新手很容易因为不懂含义而选错给后续使用埋下隐患。我按安装顺序挑重点讲。第一个重点是选择组件。默认情况下“Git Bash Here”和“Git GUI Here”两个选项已经勾选建议保留因为右键菜单里快速打开 Git Bash 确实非常实用。新版本还默认勾选了“Add a Git Bash Profile to Windows Terminal”如果你用的是 Windows 11 或较新的 Windows 10保留它即可之后在 Windows Terminal 里会多一个 Git Bash 标签页入口体验很顺滑。第二个重点是默认编辑器。Git 默认使用 Vim 作为编辑器用来打开 commit message 的编辑窗口。对于从没接触过 Vim 的人来说一不留神进入那个界面就不知道怎么退出非常劝退。我的建议是如果你平时用 VS Code、Notepad 或其他顺手编辑器就在这一步选择对应编辑器。这个选择不影响 Git 的核心逻辑只是让手动编辑提交信息时省心很多。第三个重点是调整 PATH 环境变量。这里有三个选项第一项是 “Use Git from Git Bash only”第二项是 “Git from the command line and also from 3rd-party software”第三项是 “Use Git and optional Unix tools from the Command Prompt”。我强烈建议选第二项。选第一项意味着你在 CMD 或 PowerShell 里敲git系统提示“找不到命令”这种割裂体验很不好选第三项会把一些 Unix 工具覆盖进 Windows PATH容易和系统命令产生冲突。第二项最平衡Git 被写入系统 PATH同时又不会干扰其他工具。第四个重点是 SSH 可执行文件的选择。向导中的 “Choosing the SSH executable” 建议选择 “Use Bundled OpenSSH”也就是使用 Git for Windows 自带的 OpenSSH。新版 Windows 其实也内置了 OpenSSH 客户端但为了保持密钥路径和后续 ssh-agent 配置的一致性直接用 Git 自带的那份更省心避免两套 OpenSSH 体系互相干扰。第五个重点是换行符处理。向导会问如何处理行尾默认选项是 “Checkout Windows-style, commit Unix-style line endings”这个对绝大多数 Windows 用户都是最省事的建议保留。如果团队项目对换行符有特殊要求后续可以用.gitattributes或core.autocrlf再调整这部分我会在环境配置章节展开。第六个重点是终端模拟器和 git pull 行为。终端模拟器默认是 MinTTY建议保留git pull 的默认行为选 “Default (fast-forward or merge)” 就好。最后还有 Git Credential Manager、文件系统缓存等选项保持默认即可。记住一个原则不是每个“下一步”都要改绝大多数保持默认反而最稳。2.3 安装完成后怎么确认 Git 真的能用安装完成后打开一个新的 CMD 或 PowerShell 窗口输入git --version。如果看到类似git version 2.47.0.windows.1的输出说明安装成功且 Git 已经正确加入 PATH 环境变量。如果没有识别到命令先检查安装时是不是选了 “Use Git from Git Bash only” 那个选项或者重启一下终端再试一次因为环境变量变更需要新开的窗口才会生效。接着在桌面任意空白处单击鼠标右键如果能看到 “Open Git Bash here” 菜单项说明右键菜单也注册好了。打开 Git Bash输入git help看到一段命令帮助列表输出说明这套基础环境已经可以正常使用。到了这一步Git 本体已经安装完成但离“可以舒服地协作开发”还差两步全局环境配置和 SSH 密钥配置。这两步我分别用两个章节来展开每一步都会说清楚为什么这样做。3. 环境配置把用户信息、编辑器、换行策略一次配齐3.1 全局用户信息设置安装完成后第一件事就是设置 Git 的全局用户名和邮箱。在 Git Bash 中执行git config --global user.name Your Name git config --global user.email youexample.com把引号里的内容替换成你的真实姓名和常用邮箱。这里有个很关键的细节邮箱最好和你在代码托管平台注册的邮箱保持一致这样你在 GitHub、Gitee 上的提交记录能正确对应到账号贡献统计也不会跑偏。为什么强调“全局”因为 Git 配置分为三个层级system系统级对所有用户生效、global当前用户生效、local当前仓库生效。优先级从高到低是 local、global、system。可以通过git config --list查看当前生效的所有配置也可以用git config --list --show-origin查看每项配置的来源文件。我遇到过不少同事在一台新电脑上发现提交者名字不对最后排查出来是之前在某个仓库里用 local 配置覆盖了全局配置。如果你希望所有仓库保持一致检查一下有没有多余的 local 层级配置即可。养成新环境第一时间配置全局信息的习惯能省掉后期很多清理历史提交记录的麻烦。3.2 默认编辑器、默认分支名和换行符策略除了用户信息还有几个全局配置值得顺手设好这些配置可以让 Git 的使用体验更贴近你的工作习惯。一个是默认编辑器。如果你在安装向导时选了 VS Code就不用额外配置但如果安装完了才发现默认编辑器还是 Vim可以在 Git Bash 里执行git config --global core.editor code --wait这是把 Git 的默认编辑器指定为 VS Code。如果你用其他编辑器把code换成对应编辑器的可执行文件命令即可。--wait参数的意思是 Git 会等待编辑器关闭后再继续执行确保你写完 commit message 返回命令行时Git 能读到保存的内容。另一个值得配置的是默认分支名。Git 在本地初始化仓库时默认分支名是master而 GitHub 等平台现在默认叫main。虽然平台建仓库时可以自由指定但本地初始化时如果不想每次手动git branch -M main可以设置git config --global init.defaultBranch main这样本地新建仓库时初始分支名就会是main和主流代码托管平台保持一致。换行符策略也建议在全局层面明确。Windows 上文件默认使用 CRLF 作为行尾Linux 和 macOS 上则使用 LF。如果不处理很容易出现“整个文件都被判定为修改”的尴尬情况。对 Windows 用户来说最省心的方案是让 Git 在 checkout 时把 LF 转成 CRLF在 commit 时把 CRLF 转回 LFgit config --global core.autocrlf true如果你主要维护跨平台开源库或团队已经用.gitattributes统一了规则可以把autocrlf设置为input表示 checkout 时不转换、commit 时统一转成 LF。这个参数怎么设最好以团队统一规则为准全局配置只负责你的本机默认行为。3.3 配合 VS Code / Windows Terminal 使用的小技巧现在很多人的 Windows 开发环境早已告别传统 CMD改用 Windows Terminal 和 VS Code。这两个工具和 Git 的配合有不少小技巧可以避免日常使用中的别扭感。Windows Terminal 如果之前安装时勾选了 “Add a Git Bash Profile”打开后下拉标签页菜单就能看到 Git Bash 入口直接进入和 Git Bash 完全一致的环境同时复用 Windows Terminal 的主题、字体和多标签布局。如果没有这个入口也可以手动在 Windows Terminal 配置文件里新增一个 profile可执行文件指向C:\Program Files\Git\bin\bash.exe。VS Code 这边只需要装好官方 Git 扩展然后打开任意项目文件夹左侧源代码管理面板就会显示 Git 状态。只要你在系统终端里配置好了全局用户信息和 SSH 密钥VS Code 里的 Git 操作会直接继承这些配置不用重复设置。重点提醒一下VS Code 默认的集成终端也必须能调用git命令这就是我在安装章节强调 PATH 选项选第二项的原因。另外Windows 下 Git 对中文文件名默认会转义显示表现为中文变成\xxx这样的八进制符号。建议执行git config --global core.quotepath false然后确保 Git Bash 和 VS Code 终端都使用 UTF-8 编码。这个小配置对国内用户来说几乎是刚需设置后git status和git log里就能正常显示中文文件名了。4. SSH 密钥从生成到关联代码托管平台4.1 公私钥原理为什么 SSH 更安全更方便SSH 认证的本质是“你能证明自己持有某把私钥”。整个流程可以简单理解成你在本地生成一对密钥私钥只有你自己有公钥可以公开给任何需要验证你身份的服务器。当你要连接服务器时服务器会构造一个只有持有私钥的人才能正确回应的挑战验证通过就认为你是“本人”从而允许 clone、push、pull。对比 HTTPS 每次输入账号密码SSH 的最大优势是配置好后几乎“无感”。推送代码自动走密钥验证不需要手动输入凭据脚本化和自动化部署也因此高效很多。安全性方面只要私钥不泄露公钥随便分发都没有风险。4.2 在 Git Bash 里生成 SSH 密钥生成密钥最常用的工具是ssh-keygen。Git for Windows 自带 OpenSSH所以 Git Bash 天然支持这个命令。在 Git Bash 中执行ssh-keygen -t ed25519 -C youexample.com-t指定密钥类型ed25519是目前公认安全且速度快的算法-C是注释字段一般填邮箱主要是为了在服务器上能认出这把密钥的用途。如果你所在的团队或旧系统不支持 ed25519可以用 RSA 算法ssh-keygen -t rsa -b 4096 -C youexample.com4096 位的 RSA 安全性足够只是密钥更长生成和校验速度略慢。我的个人习惯是能上 ed25519 就优先上 ed25519。执行命令后ssh-keygen会提示输入保存位置默认是C:\Users\你的用户名\.ssh\id_ed25519直接回车使用默认路径即可。接着会问是否设置 passphrase口令。这一步可以留空但如果你希望更安全建议设一个口令。设置口令后每次使用密钥都会要求输入体验会打折扣可以用 ssh-agent 把口令缓存起来解决。为了让后续连接更顺畅可以先把私钥加入 ssh-agenteval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519eval $(ssh-agent -s)是启动 ssh-agent 后台服务ssh-add则是把私钥加载进当前会话。这样在当前终端会话里使用 SSH 时不需要反复输入口令。4.3 把公钥添加到 GitHub / Gitee生成密钥后本机的~/.ssh目录下会多出两个文件没有扩展名的是私钥以.pub结尾的是公钥。私钥绝对不能泄露公钥才是要交给托管平台的内容。查看公钥内容的方法是在 Git Bash 中执行cat ~/.ssh/id_ed25519.pub输出是一段以ssh-ed25519 AAAA...开头的完整字符串复制它。然后登录代码托管平台。以 GitHub 为例进入 Settings SSH and GPG keys点击 “New SSH key”Title 里给这把密钥起个名字比如“我的笔记本电脑”Key 文本框中粘贴刚才复制的公钥内容保存即可。Gitee 的操作路径类似在“设置 SSH 公钥”中粘贴公钥并保存。很多用户在这里会犯一个糊涂公钥怎么这么长粘贴会不会有问题不需要担心公钥本来就该是一整行长文本从ssh-ed25519一直到最后全部复制、不要漏字符、不要加空格。如果复制不完整服务器验证时就会直接拒绝。4.4 测试连接怎么判断配置成功配置完公钥最好做一次联调测试。GitHub 和 Gitee 都提供了测试命令。在 Git Bash 中执行ssh -T gitgithub.com首次连接时可能会出现 Are you sure you want to continue connecting (yes/no) 的提示这是正常的指纹确认环节输入yes回车即可。如果一切正常会输出类似Hi your-username! Youve successfully authenticated, but GitHub does not provide shell access.看到这句说明认证已经成功。如果是 Gitee执行ssh -T gitgitee.comGitee 会返回类似 “Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.” 的信息。到这里SSH 密钥的完整链路就通了。你可以实际测试一下直接git clone gitgithub.com:yourname/yourrepo.git拉取一个仓库或者在已有仓库里正常 push体验一下不再输密码的感觉。5. 配置过程中最常见的报错与排查实录5.1 提交时报 Please tell me who you are这是新手最容易遇到的问题。当你在没有配置全局用户信息的仓库里执行git commit时Git 会提示你需要设置 user.name 和 user.email。解决办法就是执行上一章的两个全局配置命令git config --global user.name Your Name git config --global user.email youexample.com如果只想对当前仓库生效不覆盖全局可以在仓库目录里去掉--global。排查时用git config user.name和git config user.email分别确认当前生效值即可。这个报错本身很简单但我在团队环境里确实见过不少人因为新电脑没配置全局信息导致提交记录里出现一堆无法识别的作者名后期清理非常痛苦。规范做法是拿到新电脑就先把全局信息配好。5.2 SSH 认证失败 Permission denied (publickey)如果连接时报Permission denied (publickey)最常见的原因有三个公钥没有正确添加到代码托管平台、私钥没有加载进 ssh-agent、或者连接的账号和公钥对应的账号不一致。排查顺序建议这样走先执行ssh-add -l查看 ssh-agent 是否已经加载私钥如果没有任何输出就执行ssh-add ~/.ssh/id_ed25519重新加载。然后检查本地使用的公钥内容cat ~/.ssh/id_ed25519.pub确认是不是之前添加的那段。最后到平台设置里确认公钥对应的账号就是你当前想连接的账号。还要注意同时使用多个平台时不要弄混公钥。比如在 Gitee 添加的是 A 机器的公钥本地却用 B 机器的私钥去连接自然会失败。多账号场景下可以通过编辑~/.ssh/config文件为不同域名指定不同的密钥文件。5.3 连接超时或一直卡在连接中连接代码托管平台时偶尔会遇到 SSH 连接超时或一直卡住的问题。很多人第一反应是网络问题这里我建议先做两步基础排查第一步用ping github.com看 DNS 解析是否正常虽然ping不通不一定代表连不上但如果完全超时说明网络链路大概率有问题。第二步执行ssh -vT gitgithub.com通过详细日志看卡在哪一步是真正连不上还是认证被拒。日志里debug1信息会给出比较明确的阶段提示。如果确认是 22 端口被网络环境限制GitHub 提供了通过 443 端口连接 SSH 的方式。你可以先临时测试ssh -T -p 443 gitssh.github.com能成功的话再把连接配置固化到~/.ssh/config文件里Host github.com Hostname ssh.github.com Port 443 User git这样后续git push和git clone都会自动走 443 端口。注意这只是换了端口没有增加任何绕过能力更不是为了访问任何不该访问的服务只是为了解决部分网络环境下 22 端口不可达的问题。5.4 中文文件名乱码与换行符警告中文乱码在 Git 的 Windows 客户端上很常见。首先要确保 Git Bash 窗口的编码是 UTF-8如果配合 Windows Terminal 使用一般默认没问题。然后执行git config --global core.quotepath false这样git status和git log就不会把中文文件名转成\xxx格式。如果终端里中文提交信息还是乱码检查系统区域设置在“控制面板 区域 管理 更改系统区域设置”里勾选“Beta: 使用 Unicode UTF-8 提供全球语言支持”重启后通常能解决。换行符警告则常见于core.autocrlf设置不正确的情况。比如 clone 一个仓库后修改了一个文件git diff却发现整个文件都被标记为修改多半就是换行符被转换了。解决方法是统一全局配置把core.autocrlf设为true或者让团队通过.gitattributes固定文件换行符规则。这个问题需要结合项目实际情况处理但只要理解了 CRLF 和 LF 的转换逻辑遇到报错时就不会慌。6. 一套顺手的环境配置速查表命令直接复制6.1 常用配置命令汇总我把上面提到的核心配置整理成一张表格装完 Git 后可以直接照着执行省去来回翻文章的麻烦。配置目的命令说明查看 Git 版本git --version确认安装成功和 PATH 是否正确配置用户名git config --global user.name Your Name提交记录里的作者名配置邮箱git config --global user.email youexample.com建议和代码托管平台邮箱一致设置默认编辑器git config --global core.editor code --wait把 Vim 换成 VS Code设置默认分支git config --global init.defaultBranch main本地初始化仓库时默认 main处理换行符git config --global core.autocrlf trueWindows 下推荐配置关闭中文转义git config --global core.quotepath false让中文文件名正常显示查看全部配置git config --list排查配置问题时常用生成 SSH 密钥ssh-keygen -t ed25519 -C youexample.com密钥类型推荐 ed25519加载私钥到 agentssh-add ~/.ssh/id_ed25519减少口令输入测试 GitHub 连接ssh -T gitgithub.com验证 SSH 是否配通测试 Gitee 连接ssh -T gitgitee.com验证 SSH 是否配通6.2 多平台多密钥的管理思路如果你同时使用 GitHub、Gitee甚至公司 GitLab多个账号的密钥管理可以用一个~/.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 Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_gitlab生成密钥时给不同平台生成不同的密钥文件然后在 config 里指认好对应关系。这样切换平台时SSH 会根据目标域名自动选择匹配的私钥不用每次手动调整也不会再出现“公钥不匹配”的报错。这套思路刚开始配置时会觉得繁琐但一旦配好以后在新电脑上只需要把密钥和 config 文件迁移过去就能快速恢复完整开发环境。我个人一般会在生成密钥后就顺手备份私钥到加密的移动硬盘或密码管理器里避免电脑意外损坏后无法访问远程仓库。我当年第一次在 Windows 上配置 Git 时也栽在“没配全局用户信息”这个问题上当时完全不理解为什么提交本地仓库都要报错。后来把环境配置和 SSH 密钥彻底弄明白整个 push/pull 流程就再也没被这些基础问题卡过。这几年帮别人排查 Git 环境问题遇到最多的还是那几个老毛病PATH 没选对、用户信息没配、公钥没复制完整。只要把下载、安装、环境配置、SSH 密钥这四步都走完并且理解每一步在解决什么问题Windows 下的 Git 使用体验其实非常顺滑。最后再分享一个小技巧如果你经常需要在新电脑上快速恢复环境可以把常用全局配置命令整理成一个脚本装完 Git 后直接执行两分钟就能完成整套环境配置。SSH 密钥则建议生成时做好私钥备份这样就算电脑更换或系统重装也能及时恢复对远程仓库的访问权限不至于影响开发进度。