尧图网页设计 
很多刚接触 Git 的朋友在 Windows 上真正动手的第一步就卡住了Git 官网下载慢、安装界面一堆选项不知道点什么、装完之后终端里敲git --version没反应、好不容易把代码推上去每次都要输密码甚至有时干脆报权限错误。这些坑我都踩过当年为了把一台新电脑的环境配好前前后后折腾了一晚上。这篇文章写给所有准备在 Windows 上正式使用 Git 的人从 0 到 1 把完整流程走一遍Git 的下载与安装、安装选项怎么选、环境变量的原理和配置、SSH 密钥的生成与托管平台配置、多平台多密钥管理以及我碰到的常见报错和解决思路。不管你是刚入行的前端、打算用 VS Code 写代码的学生还是想把 Windows 当成主力开发机的老手按这篇文章走完基本不会再被环境问题绊住。全文所有操作我都按“为什么这样做”来讲而不只是丢给你一串命令。1. 下载 Git 之前先把这几件事想明白很多教程上来就让你点官网下载然后一直点 Next装完发现自己和别人电脑上的行为完全不一样问题出在你根本没搞懂 Windows 上的 Git 是个什么东西。1.1 Git 在 Windows 上的本质不是一个“程序”而是一整套环境在 Linux 或者 macOS 上Git 是系统自带的命令行工具天然和终端融为一体。但 Windows 本身没有原生的 Git 命令你在 Windows 上装的 Git实际上是 Git for Windows —— 一个把 Git 核心、Bash 终端、SSH 客户端、文件工具打包在一起的发行版。这意味着两件事第一安装时要选的东西比想象中多。第二装完之后你不只是多了一个git命令还多了一个类似 Linux 终端的 Git Bash后面生成 SSH 密钥、跑ssh命令我都建议在这个 Git Bash 里操作兼容性最好。1.2 版本选择别追新认准“官方稳定版”Git 的 Windows 版分两大类官方原版和第三方封装版比如某些工具内置的 PortableGit。个人使用我强烈建议只认准官方原版。官方下载页面地址很好记git-scm.com进去之后会自动识别你的 Windows 系统自动跳到下载页。如果没自动识别就手动选一下64 位系统选 64-bit Git for Windows Setup绝大多数现代的电脑都是 64 位。32 位的老机器已经很少见了选 32-bit 版即可。版本号不需要纠结以官网当前最新稳定版为准。Git 的版本迭代很快但核心操作、配置项、命令格式非常稳定不会因为版本升级而让你学的东西作废。官网下载慢是常态国内用户可以用清华镜像源或者华为云镜像源地址把官网下载链接的主域名换成镜像域名就行。注意下载时认清文件名里带 Setup 的安装包比如 Git-2.xx.x-64-bit.exe不要误下成源码包。源码包是给开发者编译用的普通用户直接下安装包。1.3 顺手确认 Windows 版本和终端环境安装前先看一眼你的 Windows 是 Win10 还是 Win1164 位还是 32 位。在“设置 → 系统 → 系统信息”里能看到。Win10 版本太老的话比如 1809 之前个别 Git 新特性可能不完全兼容最好先把 Windows 更新打了新版本。终端方面能用 Windows Terminal 就用它比系统自带的控制台好用得多支持多标签页和更好的中英文显示。这个不是必须的但确实能提升日常使用的幸福感。2. 下载安装全流程每一步该点什么我都给你翻译明白了这一节可能是全网最啰嗦但最实用的安装说明因为我不打算让你一路 Next而是让你知道自己点的每一个选项是在干嘛。2.1 安装界面逐项拆解双击下载好的安装包首先出现的是 GPL 许可声明页直接 Next。接着是安装路径选择默认在C:\Program Files\Git不需要改除非你的 C 盘空间实在紧张。然后进入“Select Components”页面有几个勾选项Additional icons建议勾上会在桌面生成一个 Git Bash 的快捷方式后续很多操作都从它进。Windows Explorer integration建议都勾上这样在文件夹右键菜单里会多出“Git Bash Here”和“Git GUI Here”能在任意文件夹快速打开终端效率翻倍。Associate .git configuration files with default editor勾上让.gitconfig配置文件默认用文本编辑器打开以后改配置方便。Associate .sh files to be run with Bash这一项默认不勾保持默认即可不要勾。勾上之后.sh文件会被 Git 的 Bash 默认接管可能影响系统和其他工具的行为。之后是“Select Start Menu Folder”保持默认即可。来到关键页“Selecting the default editor used by Git”这里默认是 Vim。很多新手在这步没注意之后一执行git commit就卡在 Vim 界面里不知道怎么退出只能在网上搜“怎么退出 Vim”。我的建议是如果你平时写代码用的是 VS Code就把默认编辑器改成 Visual Studio Code。如果平时不用编辑器或者想保持最纯净的状态可以继续用 Vim但你需要额外知道 Vim 的基本操作——i进入编辑模式、写完后按Esc再输入:wq回车保存退出。2.2 PATH 环境变量三条分支怎么选接下来是“Adjusting your PATH environment”页面这部分非常关键选项影响你之后能不能在任意终端里直接使用git命令。三个选项的含义Use Git from Git Bash only只能在 Git Bash 里用 git 命令在 CMD 或 PowerShell 里输入git没有任何反应。Git from the command line and also from 3rd-party software推荐把 Git 添加到系统 PATHCMD、PowerShell、Git Bash 都能直接运行 git 命令。这个是绝大多数人的首选。Use Git and optional Unix tools from the Command Prompt把 Git 的 Unix 工具也加进 PATH比如把find、sort这些命令覆盖到 Windows 同名命令。不推荐很容易造成命令冲突。选第二条。接下来是“Choosing the SSH executable”。这里默认是“Use bundled OpenSSH”意思是使用 Git 自带的 SSH 客户端。如果你把 Windows 自带的 OpenSSH 也装在系统里这里也可以选第三项“Use external OpenSSH”但默认的 bundled OpenSSH 最省事密钥、连接行为都在 Git 自己的体系内不容易出幺蛾子。保持默认。“Choosing HTTPS transport backend”这一页默认是“Use the native Windows Secure Channel library”这个选项让 Git 使用 Windows 自带的证书库管理 HTTPS 连接在企业内网、自签证书的场景下更兼容。另一选项是 OpenSSL。对普通用户来说默认项最稳保持默认即可。2.3 换行符处理最容易被忽略的坑接下来是经典的“Line Ending Conversions”页面处理 Windows 和 Linux/macOS 换行符差异的问题。这个问题可以这样理解Windows 的文本文件换行用的是“回车加换行”CRLF而 Linux/macOS 用的是“换行”LF。如果一个项目里既有 Windows 开发者又有 Linux 开发者换行符不统一会出现整个文件都被判定为“已修改”的情况非常恼火。Checkout Windows-style, commit Unix-style line endings默认推荐拉代码时自动转成 Windows 的 CRLF提交时转回 LF。适合多数人尤其是和跨平台团队协作的场景。Checkout as-is, commit Unix-style line endings拉代码时保持原样提交时转 LF。适合你确定项目里只有你自己或者大家都遵守 LF 规则的场景。Checkout as-is, commit as-is完全不转换适合只在本机使用的情况。个人开发或者团队规模不大可以选第二或第三项团队协作跨平台选第一项最安全。这里很多人直接 Next结果后面莫名其妙多出来一堆 diff多半就是换行符的统一策略没想明白。后期也可以随时随地用git config core.autocrlf修改但没有提前理解原理的人永远不会想到是这里的问题。接下来是“Configuring the terminal emulator to use with Git Bash”默认选“Use MinTTY”。MinTTY 是一个更好用的终端模拟器支持调整窗口大小、复制粘贴更顺手。另一项“Use Windows’ default console window”则是老式的控制系统台显示效果差一些。选默认的 MinTTY。再往后是“Default git pull behavior”和“Credential Manager”页都保持默认。“Enable file system caching”保持默认勾选这是为了提升 Git 在 Windows 上的文件操作性能。“Enable symbolic links”这一项别勾Windows 上符号链接需要管理员权限日常开发用不到勾了反而可能带来权限问题。2.4 安装完成后的第一件事验证命令是否生效安装完成后桌面上会出现 Git Bash 的图标。第一次打开 Git Bash你会看到一个类似 Linux 终端的窗口。在这里输入git --version正常会显示类似git version 2.50.1.windows.1这样的输出。然后验证安装时选的环境配置是否真正生效打开系统自带的 CMDWinR 输入 cmd 回车在 CMD 里执行git --version。如果也有版本输出说明 Git 已经写入了系统 PATH后面的 VS Code、PowerShell 里都能直接用 git 命令了。如果在 CMD 里提示“不是内部或外部命令”先别急着重装更常见的情况是你安装时选的是第一项“Git from Git Bash only”解决方法是下一节手动添加 PATH或者直接修复安装重选第二项。3. 装完别急着用环境变量与基础配置一次调好不少人安装完后直接 clone 仓库结果终端里显示“remote: Repository not found”或者每次操作都要输入密码。原因不是 Git 坏了而是环境变量和用户配置这一层没处理好。3.1 Windows PATH 到底是怎么一回事PATH 是 Windows 里的一个环境变量它的值是一堆文件夹路径用分号隔开。你在任意目录打开终端敲一个命令比如git系统会从当前目录开始找有没有这个程序找不到就去 PATH 列出的所有文件夹里挨个找找到了就执行它。所以 Git 安装时把C:\Program Files\Git\cmd这个路径加进 PATH你在任何地方敲git都能找到它。如果没生效除了安装时选错的场景还有一种可能是你安装 Git 之前就打开着其他软件比如已经开着的 VS Code 或较老的终端程序这些程序的环境变量是启动时读取的不会实时刷新。解决方法很简单关掉所有老终端和 IDE重新打开就能识别新加入的 PATH。还是不行的话可以手动打开“设置 → 系统 → 关于 → 高级系统设置 → 环境变量”在“系统变量”里找到Path编辑确认C:\Program Files\Git\cmd在列表里。不在的话就手动添加。3.2 Git 的三级配置体系system、global、localGit 的配置是分层的遵循“近处覆盖远处”的原则system整台机器所有用户通用配置文件在 Git 安装目录下的etc\gitconfig。global当前用户的所有仓库都生效配置文件在C:\Users\你的用户名\.gitconfig。local只对当前这个仓库生效配置文件在仓库的.git\config。在 Git Bash 里分别对应三个参数--system、--global、--local。不加参数的时候默认修改的是 local。最常用的两条 global 配置是用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com为什么这俩必须配因为每一次 commit 都会记录作者信息如果没有设置Git 会报错或者用你系统的主机名生成一个莫名其妙的默认值。这个写进历史里的信息改起来很麻烦所以一开始就配好。查看所有配置git config --global --list3.3 换行符、默认分支名、别名和终端编码一次配全除了用户名和邮箱我每次在新电脑上都会把下面这几条一起配好git config --global init.defaultBranch main这一行把新仓库的默认分支名从master改成main。纯粹是个人偏好现在 GitHub 和 Gitee 新建仓库的默认分支都是 main本地统一用 main少很多心智负担。git config --global core.autocrlf trueWindows 用户建议显式设成true对应安装向导第一项换行符策略明确让 Git 在拉代码时转 CRLF、提交时转 LF。如果之前选的是 as-is也可以在这里改。git config --global core.quotepath false这个配置解决一个中文用户很烦的问题——不设置的话文件名里有中文会显示成\346\265\213\350\257\225这样的乱码转义序列。设成 false 后git status里能正常显示中文文件名。git config --global gui.encoding utf-8让 Git GUI如果你用的话也统一用 UTF-8 编码显示提交信息。再顺手设两个高频别名能明显提高日常操作效率git config --global alias.st status git config --global alias.lg log --oneline --graph --all --decorate以后敲git st就是查看状态敲git lg就是看一条带分支图的提交历史比默认的git log直观得多。3.4 配置完的验证与常见困惑所有配置写完后可以检查一遍整体配置git config --global --list但它只会列出有值的项。想看配置项来自哪个层级、当前生效值是多少用git config --show-origin --get user.name这个命令会告诉你这个值是写在哪个文件里的排查“改了半天不生效”的问题特别有用因为很可能是同名的配置项在 system 级先设了一个值global 级又设了一个值而 local 级里又在别处定义了最后生效的优先级会让你困惑。4. SSH 密钥这块原理和实操一起讲透每次都用 HTTPS 地址 clone 或 push被要求输用户名密码虽然 Windows 凭据管理器可以记住但总归麻烦而且有些环境比如公司内部 GitLab 强制用 SSH根本绕不开 SSH 这条路径。所以这一步才是整个环境配置里最值得花心思的部分。4.1 为什么 Git 要优先用 SSH 而不是 HTTPSGit 远程仓库支持两种主要协议HTTPS 和 SSH。HTTPS 的优点是简单仓库地址就是网页地址任何人拿到地址都能访问权限在服务端控制。缺点是每次交互要证明“你是谁”虽然可以靠记住密码来缓解但在多设备、多平台的场景下每台设备都要处理一次凭据很容易漏。SSH 的优点是一次配置、永久免密而且它建立了一条加密通道内容不会被抓包。它的原理是非对称加密你手上有两把“钥匙”一把是私钥private key留在自己电脑上绝对不能给任何人另一把是公钥public key可以公开把它放到 GitHub、Gitee 或者公司 GitLab 服务端的 SSH Keys 设置里。当 Git 通过 SSH 连接服务器时服务器用你的公钥验证你的私钥是否配对成功配对上了就放行。可以这样理解公钥是一把锁私钥是唯一的钥匙。你把锁挂到门上之后只要掏出钥匙能打开这把锁门就让你进。钥匙丢了或者锁配错了门就进不去。4.2 生成密钥前的准备确认 SSH 客户端可用在 Git Bash 里先确认一下有没有 SSH 客户端ssh -V有输出就说明 SSH 客户端可用。这里我强烈建议使用 Git 自带的 OpenSSH而不是 Windows 系统的 OpenSSH因为 Git 自带版本和 GitHub、Gitee 的交互调校得更好版本也更稳定后面遇到权限问题时排查范围也会小很多。Windows 自带的 OpenSSH 装在C:\Windows\System32\OpenSSHGit 自带 SSH 在 Git 安装目录的usr\bin下。如果你在 Git Bash 里跑which ssh看到的是 Git 安装目录下的路径那就没问题。如果看到的是 Windows 系统目录后面配置密钥时要特别小心以免两个客户端读取的密钥目录不一致。4.3 ssh-keygen 生成密钥算法选型与参数解释生成密钥的标准命令ssh-keygen -t ed25519 -C 你的邮箱example.com -f ~/.ssh/id_ed25519这里几个参数的含义-t ed25519指定密钥算法。ed25519 是目前综合推荐度最高的算法密钥长度短只有 256 位、安全性高、验证速度快GitHub、Gitee、GitLab 都支持。老教程里常见的-t rsa -b 4096也不是不能用但 ed25519 更现代、文件更短没有必要用更老的 RSA。-C 你的邮箱给密钥加一个注释纯粹为了让你自己知道这个密钥是干嘛用的不写也可以但写了在管理多个密钥时会轻松很多。-f ~/.ssh/id_ed25519指定密钥要保存的文件路径。默认就是~/.ssh/id_ed25519不想改可以直接省略这个参数。回车后终端会提示你输入 passphrase密码短语。这一步很关键也是新手最容易忽略的地方。4.4 passphrase 该不该设安全与便利的一次权衡passphrase 相当于给私钥加了最后一道保险。如果你设置了 passphrase即使你的私钥文件被拷走黑客没有 passphrase 也无法使用这把私钥。但它的代价是每次用 SSH 连接时Git Bash 都可能提示你输入 passphrase除非配合 ssh-agent 记住。我的建议是一定要设一个。很多人嫌麻烦直接回车跳过等到私钥真的泄露那天会后悔。实际上配合 ssh-agent你每天只需要输入一次完全值得。设完 passphrase 后~/.ssh目录下会出现两个文件id_ed25519私钥文件权限敏感绝不能给别人也不能上传到任何网盘或代码仓库。id_ed25519.pub公钥文件可以放心地到处放。查看它的内容是后面配置托管平台的必要步骤cat ~/.ssh/id_ed25519.pub输出是一段以ssh-ed25519开头、以你设置的邮箱结尾的字符串这就是你要添加给 GitHub/Gitee 的内容。提示复制公钥内容时建议用clip ~/.ssh/id_ed25519.pub命令直接把公钥复制到 Windows 剪贴板避免手动选中复制时漏掉末尾字符。5. 密钥生成后怎么放GitHub、Gitee 与多平台多密钥管理密钥生成了但如果你以为直接把公钥内容复制到平台就完事了后面连不上时又会绕回原点。放公钥这个动作很简单但在多平台、多账号的场景下有一些隐藏规则是网上很多教程不会明说的。5.1 把公钥添加到代码托管平台以 GitHub 为例登录 GitHub点右上角头像Settings → SSH and GPG keys → 点 New SSH key。Title 随便填能让你认出这台电脑就行比如my-windows-2026Key Type 保持 Authentication KeyKey 这一栏粘贴刚才复制的公钥内容最后 Add SSH key。Gitee 的入口类似设置 → SSH 公钥粘贴保存。添加完之后用测试命令验证是否通了ssh -T gitgithub.com首次连接会提示确认 host key见下一节的 known_hosts 机制输入yes回车。如果配置成功GitHub 会返回类似Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.看到这句话说明 SSH 认证已经通了。这句话不是个错误信息很多新手在这看到does not provide shell access以为自己配置失败了其实恰恰相反这是 SSH 链路完全打通的标准返回文本。Gitee 的测试命令是ssh -T gitgitee.com5.2 仓库地址切换从 HTTPS 改成 SSH如果你之前已经用 HTTPS 方式 clone 过仓库现在想切成 SSH不需要重新 clone直接修改远程地址就行git remote -v查看当前远程地址如果是 HTTPS 形式https://github.com/用户名/仓库.git改成 SSH 形式git remote set-url origin gitgithub.com:用户名/仓库.git改完再git remote -v确认一下。从此 push 和 pull 就走 SSH 通道了再也不用输密码。5.3 一台电脑管理多个平台的密钥config 文件的用法很多人有多平台的需求GitHub 一个账号、Gitee 一个账号、公司 GitLab 一个账号。如果都用同一对密钥逻辑上是没有问题的——只要是同一个人公钥放哪都认你私钥只有一把在自己手里。但有些公司会强制要求每个项目或者每个平台用不同的密钥或者你想在同一台电脑上区分“个人身份”和“公司身份”这时候就需要多对密钥。假设你生成了一对新的公司用密钥ssh-keygen -t ed25519 -C youcompany.com -f ~/.ssh/id_ed25519_company光生成还不够SSH 客户端有默认的密钥查找逻辑默认只找~/.ssh/id_ed25519。你想让它连公司 GitLab 时自动用id_ed25519_company就需要在~/.ssh/config文件中写明规则。先编辑或创建 config 文件vim ~/.ssh/config写入# GitHub 个人仓库默认密钥 Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 # 公司 GitLab使用公司密钥 Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company # Gitee与 GitHub 共用同一把默认密钥 Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519配置项的语义很清楚Host是你在远程地址里写的别名HostName是真实的服务器域名User固定填gitGit 托管平台统一用这个用户IdentityFile指定该 host 对应的私钥路径。这样 SSH 连接时就会自动选择对应的私钥。测试时直接指定 host 名ssh -T gitgithub.com ssh -T gitgitlab.company.com各自的认证会走各自的密钥规则。5.4 ssh-agent 与私钥缓存让 passphrase 只输一次设置了 passphrase 之后每次 SSH 连接都要输一次密码短语。密码复杂的话确实很烦这时可以把私钥交给 ssh-agent 这个后台进程记住。先确保 ssh-agent 正在运行Git Bash 里通常在启动时已经运行然后添加私钥eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519输入一次 passphrase 之后只要 ssh-agent 进程不结束当前 Git Bash 窗口不关闭之后所有 Git 操作都不需要再输 passphrase。关掉窗口再打开重新执行ssh-add一次即可。也可以把eval $(ssh-agent -s)和ssh-add写进~/.bashrc这样每次打开 Git Bash 自动加载但有一说一我对把 ssh-add 写进 bashrc 是持保留态度的因为你每次开窗口都会被要求输入一次 passphrase反而比按需手动ssh-add更烦。按需添加是我目前觉得最舒服的方式。如果想彻底不用输 passphrase 也不设密码短语也不是不行但前提是你得保证电脑本身的安全性比如开启了 Windows Hello 登录、磁盘加密否则私钥文件被提取出去就直接裸奔了。6. 换上 SSH 之后连接失败这类坑我给你趟一遍这部分是我实际被问得最多的地方。前几步看着都做对了但ssh -T gitgithub.com就是报错。我把高频问题按排查链路的顺序整理一下按顺序自查多数人能自己解决。6.1 Permission denied (publickey)八成是密钥没配对或者配对错了这个报错是 SSH 认证失败的经典提示。英文大意为服务器用你提供的公钥和你本地的私钥配对失败。排查链路是这样走的第一步确认你当前用的私钥是不是生成时那把ssh -vT gitgithub.com加-v参数后 SSH 会打印详细连接过程其中有一行Offering public key: ...可以看到实际提交给服务器验证的是哪个公钥。如果它显示的是其他密钥说明~/.ssh/config里指定错了路径或者默认文件名不是id_ed25519。第二步确认公钥确实添加到了平台上。回到 GitHub/Gitee 设置页把页面上的公钥串和本机的.pub文件内容仔细比对尤其是末尾的邮箱注释。很多时候是复制时多了一个空格或者少了一个前缀。第三步如果用的是多密钥场景检查 config 文件里的IdentityFile是否指向了正确的私钥host 名是否和远程地址完全一致。6.2 Host key verification failed要么换了服务器要么第一次连接时手滑了这个报错和刚才的 publickey 完全不同。它发生在最早期SSH 每次连接新服务器时会把服务器的公钥指纹记录下来存到~/.ssh/known_hosts文件里下次连接时再比对防止中间人攻击。如果服务器的 host key 变了比如平台迁移、容器重建或者 known_hosts 里之前记录过不同的指纹就会报这个错。解决方法有两种ssh-keygen -R github.com这一条删除 known_hosts 里 github.com 对应的旧记录再重新ssh -T gitgithub.com会重新提示你确认 host key输入yes保存即可。或者直接手动编辑~/.ssh/known_hosts找到对应行删掉。6.3 Connection timed out 与 Connection refused先别急着怀疑密钥如果错误是Connection timed out连接超时而不是权限问题那和密钥无关问题出在网络通路上。排查顺序先ping github.com看通不通然后再用ssh -vT看卡在哪一步。有时候是公司内网防火墙屏蔽了 SSH 端口22这种情况你可能需要用 SSH over HTTPS 端口443的方式连。GitHub 官方支持这个方案在~/.ssh/config里加Host github.com HostName ssh.github.com Port 443 User git这是 GitHub 官方推荐的变通方案。注意这里HostName改成了ssh.github.com端口变成 443。改完后ssh -T gitgithub.com再试如果能通过说明你本地的 22 端口确实被网络策略限制了443 端口方案完美绕开。6.4 仓库地址写错导致连接目标不对还有一个很低级但很常见的坑远程地址里把git写成了其他用户名或者把gitgithub.com:后面的路径写错了。检查命令git remote -v如果发现远程地址不是你期望的 SSH 形式用之前讲的git remote set-url origin改正。6.5 VS Code 里连不上远程服务器的问题很多 Windows 开发者会顺便把 VS Code 和 Remote-SSH 插件配起来连接公司的 Linux 服务器写代码。如果你在 Git Bash 里 SSH 连接是通的但 VS Code 连不上大概率是 VS Code 的 SSH 扩展调用的 SSH 客户端和环境和 Git Bash 里调用的不是同一个。解决思路在 VS Code 设置里搜remote.SSH.path把它显式指定为 Git 安装目录下的usr\bin\ssh.exe。这个设置很重要因为 VS Code 在 Windows 上默认找系统 OpenSSH和你的 Git 密钥可能不在一个体系。确认 VS Code 下载安装 Remote-SSH 扩展时用的网络环境正常这个扩展需要在 VS Code 内完成安装。在 VS Code 命令面板执行Remote-SSH: Settings把Config File指向C:\Users\你的用户名\.ssh\config确保 VS Code 能读到你的多密钥配置。VS Code 的坑往往不在联机阶段而在“连上了但扩展无法在远程正常运行”。如果出现提示说某个扩展被禁用因为被定义为在远程扩展主机中运行这通常是扩展本身声明了仅支持远程或仅支持本地去扩展详情页看是否要选 install in SSH host 即可不是环境问题。6.6 改完配置不生效优先怀疑缓存和重开Windows 下配置写完不生效最常见的原因是终端/IDE 是之前打开的环境变量和 ssh-agent 都还是旧状态。所以一个很朴素的排查原则把所有相关程序全关掉重新打开一次。Git Bash、CMD、VS Code 全部退出重进。Windows 的 Shell 不会自动感知.bashrc或环境变量的变更只有重启才能让它重新加载。如果要确定配置文件被正确读取可以在 Git Bash 里手动 source 一次source ~/.bashrc但更彻底的验证方式还是重开窗口。6.7 Git 命令的日常高频操作顺手把最常用的列出来环境配好之后日常开发用得最多的命令其实就那么几条。给刚上手的朋友一次性列全省得到处翻文档git clone gitgithub.com:用户名/仓库.git # 克隆远程仓库 git status # 查看工作区状态 git add . # 把所有改动加入暂存区 git commit -m 提交说明 # 提交到本地仓库 git push origin main # 推送到远程 main 分支 git pull origin main # 拉取远程最新代码 git branch -a # 查看所有分支 git checkout -b feature/xxx # 新建并切换分支 git log --oneline --graph --all # 查看提交历史配合之前配的别名 git lg这些命令不需要背用得多了自然就记住了。关键是把环境和 SSH 链路配好后面的路就顺畅了。最后再分享一个实战中得到的经验配置 SSH 密钥时passphrase 不要嫌麻烦跳过建议设一个强度高、有规律、自己一定记得住的密码短语。我见过太多同事嫌麻烦不设密码短语结果装有私钥文件的电脑被别人摸了一下仓库连同服务器权限一块儿拱手让人。反过来设了密码短语之后只要你自己记得住配合 ssh-agent体验上和没设没任何区别安全性却不是一个级别。另外如果你在重装系统或者换了新电脑记得把~/.ssh目录和~/.gitconfig文件提前备份出来。我给自己的电脑做环境迁移时就是把这俩文件拷到新机器上省掉了重新生成密钥、重新配置 user 信息的所有时间。密钥文件本质是文本文件U盘拷贝完全没问题注意别上传到网盘和代码仓库就行。整个环境的“搬家”工作量其实比你想象中小得多。 Windows上Git安装配置与SSH密钥管理完整指南
很多刚接触 Git 的朋友在 Windows 上真正动手的第一步就卡住了Git 官网下载慢、安装界面一堆选项不知道点什么、装完之后终端里敲git --version没反应、好不容易把代码推上去每次都要输密码甚至有时干脆报权限错误。这些坑我都踩过当年为了把一台新电脑的环境配好前前后后折腾了一晚上。这篇文章写给所有准备在 Windows 上正式使用 Git 的人从 0 到 1 把完整流程走一遍Git 的下载与安装、安装选项怎么选、环境变量的原理和配置、SSH 密钥的生成与托管平台配置、多平台多密钥管理以及我碰到的常见报错和解决思路。不管你是刚入行的前端、打算用 VS Code 写代码的学生还是想把 Windows 当成主力开发机的老手按这篇文章走完基本不会再被环境问题绊住。全文所有操作我都按“为什么这样做”来讲而不只是丢给你一串命令。1. 下载 Git 之前先把这几件事想明白很多教程上来就让你点官网下载然后一直点 Next装完发现自己和别人电脑上的行为完全不一样问题出在你根本没搞懂 Windows 上的 Git 是个什么东西。1.1 Git 在 Windows 上的本质不是一个“程序”而是一整套环境在 Linux 或者 macOS 上Git 是系统自带的命令行工具天然和终端融为一体。但 Windows 本身没有原生的 Git 命令你在 Windows 上装的 Git实际上是 Git for Windows —— 一个把 Git 核心、Bash 终端、SSH 客户端、文件工具打包在一起的发行版。这意味着两件事第一安装时要选的东西比想象中多。第二装完之后你不只是多了一个git命令还多了一个类似 Linux 终端的 Git Bash后面生成 SSH 密钥、跑ssh命令我都建议在这个 Git Bash 里操作兼容性最好。1.2 版本选择别追新认准“官方稳定版”Git 的 Windows 版分两大类官方原版和第三方封装版比如某些工具内置的 PortableGit。个人使用我强烈建议只认准官方原版。官方下载页面地址很好记git-scm.com进去之后会自动识别你的 Windows 系统自动跳到下载页。如果没自动识别就手动选一下64 位系统选 64-bit Git for Windows Setup绝大多数现代的电脑都是 64 位。32 位的老机器已经很少见了选 32-bit 版即可。版本号不需要纠结以官网当前最新稳定版为准。Git 的版本迭代很快但核心操作、配置项、命令格式非常稳定不会因为版本升级而让你学的东西作废。官网下载慢是常态国内用户可以用清华镜像源或者华为云镜像源地址把官网下载链接的主域名换成镜像域名就行。注意下载时认清文件名里带 Setup 的安装包比如 Git-2.xx.x-64-bit.exe不要误下成源码包。源码包是给开发者编译用的普通用户直接下安装包。1.3 顺手确认 Windows 版本和终端环境安装前先看一眼你的 Windows 是 Win10 还是 Win1164 位还是 32 位。在“设置 → 系统 → 系统信息”里能看到。Win10 版本太老的话比如 1809 之前个别 Git 新特性可能不完全兼容最好先把 Windows 更新打了新版本。终端方面能用 Windows Terminal 就用它比系统自带的控制台好用得多支持多标签页和更好的中英文显示。这个不是必须的但确实能提升日常使用的幸福感。2. 下载安装全流程每一步该点什么我都给你翻译明白了这一节可能是全网最啰嗦但最实用的安装说明因为我不打算让你一路 Next而是让你知道自己点的每一个选项是在干嘛。2.1 安装界面逐项拆解双击下载好的安装包首先出现的是 GPL 许可声明页直接 Next。接着是安装路径选择默认在C:\Program Files\Git不需要改除非你的 C 盘空间实在紧张。然后进入“Select Components”页面有几个勾选项Additional icons建议勾上会在桌面生成一个 Git Bash 的快捷方式后续很多操作都从它进。Windows Explorer integration建议都勾上这样在文件夹右键菜单里会多出“Git Bash Here”和“Git GUI Here”能在任意文件夹快速打开终端效率翻倍。Associate .git configuration files with default editor勾上让.gitconfig配置文件默认用文本编辑器打开以后改配置方便。Associate .sh files to be run with Bash这一项默认不勾保持默认即可不要勾。勾上之后.sh文件会被 Git 的 Bash 默认接管可能影响系统和其他工具的行为。之后是“Select Start Menu Folder”保持默认即可。来到关键页“Selecting the default editor used by Git”这里默认是 Vim。很多新手在这步没注意之后一执行git commit就卡在 Vim 界面里不知道怎么退出只能在网上搜“怎么退出 Vim”。我的建议是如果你平时写代码用的是 VS Code就把默认编辑器改成 Visual Studio Code。如果平时不用编辑器或者想保持最纯净的状态可以继续用 Vim但你需要额外知道 Vim 的基本操作——i进入编辑模式、写完后按Esc再输入:wq回车保存退出。2.2 PATH 环境变量三条分支怎么选接下来是“Adjusting your PATH environment”页面这部分非常关键选项影响你之后能不能在任意终端里直接使用git命令。三个选项的含义Use Git from Git Bash only只能在 Git Bash 里用 git 命令在 CMD 或 PowerShell 里输入git没有任何反应。Git from the command line and also from 3rd-party software推荐把 Git 添加到系统 PATHCMD、PowerShell、Git Bash 都能直接运行 git 命令。这个是绝大多数人的首选。Use Git and optional Unix tools from the Command Prompt把 Git 的 Unix 工具也加进 PATH比如把find、sort这些命令覆盖到 Windows 同名命令。不推荐很容易造成命令冲突。选第二条。接下来是“Choosing the SSH executable”。这里默认是“Use bundled OpenSSH”意思是使用 Git 自带的 SSH 客户端。如果你把 Windows 自带的 OpenSSH 也装在系统里这里也可以选第三项“Use external OpenSSH”但默认的 bundled OpenSSH 最省事密钥、连接行为都在 Git 自己的体系内不容易出幺蛾子。保持默认。“Choosing HTTPS transport backend”这一页默认是“Use the native Windows Secure Channel library”这个选项让 Git 使用 Windows 自带的证书库管理 HTTPS 连接在企业内网、自签证书的场景下更兼容。另一选项是 OpenSSL。对普通用户来说默认项最稳保持默认即可。2.3 换行符处理最容易被忽略的坑接下来是经典的“Line Ending Conversions”页面处理 Windows 和 Linux/macOS 换行符差异的问题。这个问题可以这样理解Windows 的文本文件换行用的是“回车加换行”CRLF而 Linux/macOS 用的是“换行”LF。如果一个项目里既有 Windows 开发者又有 Linux 开发者换行符不统一会出现整个文件都被判定为“已修改”的情况非常恼火。Checkout Windows-style, commit Unix-style line endings默认推荐拉代码时自动转成 Windows 的 CRLF提交时转回 LF。适合多数人尤其是和跨平台团队协作的场景。Checkout as-is, commit Unix-style line endings拉代码时保持原样提交时转 LF。适合你确定项目里只有你自己或者大家都遵守 LF 规则的场景。Checkout as-is, commit as-is完全不转换适合只在本机使用的情况。个人开发或者团队规模不大可以选第二或第三项团队协作跨平台选第一项最安全。这里很多人直接 Next结果后面莫名其妙多出来一堆 diff多半就是换行符的统一策略没想明白。后期也可以随时随地用git config core.autocrlf修改但没有提前理解原理的人永远不会想到是这里的问题。接下来是“Configuring the terminal emulator to use with Git Bash”默认选“Use MinTTY”。MinTTY 是一个更好用的终端模拟器支持调整窗口大小、复制粘贴更顺手。另一项“Use Windows’ default console window”则是老式的控制系统台显示效果差一些。选默认的 MinTTY。再往后是“Default git pull behavior”和“Credential Manager”页都保持默认。“Enable file system caching”保持默认勾选这是为了提升 Git 在 Windows 上的文件操作性能。“Enable symbolic links”这一项别勾Windows 上符号链接需要管理员权限日常开发用不到勾了反而可能带来权限问题。2.4 安装完成后的第一件事验证命令是否生效安装完成后桌面上会出现 Git Bash 的图标。第一次打开 Git Bash你会看到一个类似 Linux 终端的窗口。在这里输入git --version正常会显示类似git version 2.50.1.windows.1这样的输出。然后验证安装时选的环境配置是否真正生效打开系统自带的 CMDWinR 输入 cmd 回车在 CMD 里执行git --version。如果也有版本输出说明 Git 已经写入了系统 PATH后面的 VS Code、PowerShell 里都能直接用 git 命令了。如果在 CMD 里提示“不是内部或外部命令”先别急着重装更常见的情况是你安装时选的是第一项“Git from Git Bash only”解决方法是下一节手动添加 PATH或者直接修复安装重选第二项。3. 装完别急着用环境变量与基础配置一次调好不少人安装完后直接 clone 仓库结果终端里显示“remote: Repository not found”或者每次操作都要输入密码。原因不是 Git 坏了而是环境变量和用户配置这一层没处理好。3.1 Windows PATH 到底是怎么一回事PATH 是 Windows 里的一个环境变量它的值是一堆文件夹路径用分号隔开。你在任意目录打开终端敲一个命令比如git系统会从当前目录开始找有没有这个程序找不到就去 PATH 列出的所有文件夹里挨个找找到了就执行它。所以 Git 安装时把C:\Program Files\Git\cmd这个路径加进 PATH你在任何地方敲git都能找到它。如果没生效除了安装时选错的场景还有一种可能是你安装 Git 之前就打开着其他软件比如已经开着的 VS Code 或较老的终端程序这些程序的环境变量是启动时读取的不会实时刷新。解决方法很简单关掉所有老终端和 IDE重新打开就能识别新加入的 PATH。还是不行的话可以手动打开“设置 → 系统 → 关于 → 高级系统设置 → 环境变量”在“系统变量”里找到Path编辑确认C:\Program Files\Git\cmd在列表里。不在的话就手动添加。3.2 Git 的三级配置体系system、global、localGit 的配置是分层的遵循“近处覆盖远处”的原则system整台机器所有用户通用配置文件在 Git 安装目录下的etc\gitconfig。global当前用户的所有仓库都生效配置文件在C:\Users\你的用户名\.gitconfig。local只对当前这个仓库生效配置文件在仓库的.git\config。在 Git Bash 里分别对应三个参数--system、--global、--local。不加参数的时候默认修改的是 local。最常用的两条 global 配置是用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com为什么这俩必须配因为每一次 commit 都会记录作者信息如果没有设置Git 会报错或者用你系统的主机名生成一个莫名其妙的默认值。这个写进历史里的信息改起来很麻烦所以一开始就配好。查看所有配置git config --global --list3.3 换行符、默认分支名、别名和终端编码一次配全除了用户名和邮箱我每次在新电脑上都会把下面这几条一起配好git config --global init.defaultBranch main这一行把新仓库的默认分支名从master改成main。纯粹是个人偏好现在 GitHub 和 Gitee 新建仓库的默认分支都是 main本地统一用 main少很多心智负担。git config --global core.autocrlf trueWindows 用户建议显式设成true对应安装向导第一项换行符策略明确让 Git 在拉代码时转 CRLF、提交时转 LF。如果之前选的是 as-is也可以在这里改。git config --global core.quotepath false这个配置解决一个中文用户很烦的问题——不设置的话文件名里有中文会显示成\346\265\213\350\257\225这样的乱码转义序列。设成 false 后git status里能正常显示中文文件名。git config --global gui.encoding utf-8让 Git GUI如果你用的话也统一用 UTF-8 编码显示提交信息。再顺手设两个高频别名能明显提高日常操作效率git config --global alias.st status git config --global alias.lg log --oneline --graph --all --decorate以后敲git st就是查看状态敲git lg就是看一条带分支图的提交历史比默认的git log直观得多。3.4 配置完的验证与常见困惑所有配置写完后可以检查一遍整体配置git config --global --list但它只会列出有值的项。想看配置项来自哪个层级、当前生效值是多少用git config --show-origin --get user.name这个命令会告诉你这个值是写在哪个文件里的排查“改了半天不生效”的问题特别有用因为很可能是同名的配置项在 system 级先设了一个值global 级又设了一个值而 local 级里又在别处定义了最后生效的优先级会让你困惑。4. SSH 密钥这块原理和实操一起讲透每次都用 HTTPS 地址 clone 或 push被要求输用户名密码虽然 Windows 凭据管理器可以记住但总归麻烦而且有些环境比如公司内部 GitLab 强制用 SSH根本绕不开 SSH 这条路径。所以这一步才是整个环境配置里最值得花心思的部分。4.1 为什么 Git 要优先用 SSH 而不是 HTTPSGit 远程仓库支持两种主要协议HTTPS 和 SSH。HTTPS 的优点是简单仓库地址就是网页地址任何人拿到地址都能访问权限在服务端控制。缺点是每次交互要证明“你是谁”虽然可以靠记住密码来缓解但在多设备、多平台的场景下每台设备都要处理一次凭据很容易漏。SSH 的优点是一次配置、永久免密而且它建立了一条加密通道内容不会被抓包。它的原理是非对称加密你手上有两把“钥匙”一把是私钥private key留在自己电脑上绝对不能给任何人另一把是公钥public key可以公开把它放到 GitHub、Gitee 或者公司 GitLab 服务端的 SSH Keys 设置里。当 Git 通过 SSH 连接服务器时服务器用你的公钥验证你的私钥是否配对成功配对上了就放行。可以这样理解公钥是一把锁私钥是唯一的钥匙。你把锁挂到门上之后只要掏出钥匙能打开这把锁门就让你进。钥匙丢了或者锁配错了门就进不去。4.2 生成密钥前的准备确认 SSH 客户端可用在 Git Bash 里先确认一下有没有 SSH 客户端ssh -V有输出就说明 SSH 客户端可用。这里我强烈建议使用 Git 自带的 OpenSSH而不是 Windows 系统的 OpenSSH因为 Git 自带版本和 GitHub、Gitee 的交互调校得更好版本也更稳定后面遇到权限问题时排查范围也会小很多。Windows 自带的 OpenSSH 装在C:\Windows\System32\OpenSSHGit 自带 SSH 在 Git 安装目录的usr\bin下。如果你在 Git Bash 里跑which ssh看到的是 Git 安装目录下的路径那就没问题。如果看到的是 Windows 系统目录后面配置密钥时要特别小心以免两个客户端读取的密钥目录不一致。4.3 ssh-keygen 生成密钥算法选型与参数解释生成密钥的标准命令ssh-keygen -t ed25519 -C 你的邮箱example.com -f ~/.ssh/id_ed25519这里几个参数的含义-t ed25519指定密钥算法。ed25519 是目前综合推荐度最高的算法密钥长度短只有 256 位、安全性高、验证速度快GitHub、Gitee、GitLab 都支持。老教程里常见的-t rsa -b 4096也不是不能用但 ed25519 更现代、文件更短没有必要用更老的 RSA。-C 你的邮箱给密钥加一个注释纯粹为了让你自己知道这个密钥是干嘛用的不写也可以但写了在管理多个密钥时会轻松很多。-f ~/.ssh/id_ed25519指定密钥要保存的文件路径。默认就是~/.ssh/id_ed25519不想改可以直接省略这个参数。回车后终端会提示你输入 passphrase密码短语。这一步很关键也是新手最容易忽略的地方。4.4 passphrase 该不该设安全与便利的一次权衡passphrase 相当于给私钥加了最后一道保险。如果你设置了 passphrase即使你的私钥文件被拷走黑客没有 passphrase 也无法使用这把私钥。但它的代价是每次用 SSH 连接时Git Bash 都可能提示你输入 passphrase除非配合 ssh-agent 记住。我的建议是一定要设一个。很多人嫌麻烦直接回车跳过等到私钥真的泄露那天会后悔。实际上配合 ssh-agent你每天只需要输入一次完全值得。设完 passphrase 后~/.ssh目录下会出现两个文件id_ed25519私钥文件权限敏感绝不能给别人也不能上传到任何网盘或代码仓库。id_ed25519.pub公钥文件可以放心地到处放。查看它的内容是后面配置托管平台的必要步骤cat ~/.ssh/id_ed25519.pub输出是一段以ssh-ed25519开头、以你设置的邮箱结尾的字符串这就是你要添加给 GitHub/Gitee 的内容。提示复制公钥内容时建议用clip ~/.ssh/id_ed25519.pub命令直接把公钥复制到 Windows 剪贴板避免手动选中复制时漏掉末尾字符。5. 密钥生成后怎么放GitHub、Gitee 与多平台多密钥管理密钥生成了但如果你以为直接把公钥内容复制到平台就完事了后面连不上时又会绕回原点。放公钥这个动作很简单但在多平台、多账号的场景下有一些隐藏规则是网上很多教程不会明说的。5.1 把公钥添加到代码托管平台以 GitHub 为例登录 GitHub点右上角头像Settings → SSH and GPG keys → 点 New SSH key。Title 随便填能让你认出这台电脑就行比如my-windows-2026Key Type 保持 Authentication KeyKey 这一栏粘贴刚才复制的公钥内容最后 Add SSH key。Gitee 的入口类似设置 → SSH 公钥粘贴保存。添加完之后用测试命令验证是否通了ssh -T gitgithub.com首次连接会提示确认 host key见下一节的 known_hosts 机制输入yes回车。如果配置成功GitHub 会返回类似Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.看到这句话说明 SSH 认证已经通了。这句话不是个错误信息很多新手在这看到does not provide shell access以为自己配置失败了其实恰恰相反这是 SSH 链路完全打通的标准返回文本。Gitee 的测试命令是ssh -T gitgitee.com5.2 仓库地址切换从 HTTPS 改成 SSH如果你之前已经用 HTTPS 方式 clone 过仓库现在想切成 SSH不需要重新 clone直接修改远程地址就行git remote -v查看当前远程地址如果是 HTTPS 形式https://github.com/用户名/仓库.git改成 SSH 形式git remote set-url origin gitgithub.com:用户名/仓库.git改完再git remote -v确认一下。从此 push 和 pull 就走 SSH 通道了再也不用输密码。5.3 一台电脑管理多个平台的密钥config 文件的用法很多人有多平台的需求GitHub 一个账号、Gitee 一个账号、公司 GitLab 一个账号。如果都用同一对密钥逻辑上是没有问题的——只要是同一个人公钥放哪都认你私钥只有一把在自己手里。但有些公司会强制要求每个项目或者每个平台用不同的密钥或者你想在同一台电脑上区分“个人身份”和“公司身份”这时候就需要多对密钥。假设你生成了一对新的公司用密钥ssh-keygen -t ed25519 -C youcompany.com -f ~/.ssh/id_ed25519_company光生成还不够SSH 客户端有默认的密钥查找逻辑默认只找~/.ssh/id_ed25519。你想让它连公司 GitLab 时自动用id_ed25519_company就需要在~/.ssh/config文件中写明规则。先编辑或创建 config 文件vim ~/.ssh/config写入# GitHub 个人仓库默认密钥 Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 # 公司 GitLab使用公司密钥 Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company # Gitee与 GitHub 共用同一把默认密钥 Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519配置项的语义很清楚Host是你在远程地址里写的别名HostName是真实的服务器域名User固定填gitGit 托管平台统一用这个用户IdentityFile指定该 host 对应的私钥路径。这样 SSH 连接时就会自动选择对应的私钥。测试时直接指定 host 名ssh -T gitgithub.com ssh -T gitgitlab.company.com各自的认证会走各自的密钥规则。5.4 ssh-agent 与私钥缓存让 passphrase 只输一次设置了 passphrase 之后每次 SSH 连接都要输一次密码短语。密码复杂的话确实很烦这时可以把私钥交给 ssh-agent 这个后台进程记住。先确保 ssh-agent 正在运行Git Bash 里通常在启动时已经运行然后添加私钥eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519输入一次 passphrase 之后只要 ssh-agent 进程不结束当前 Git Bash 窗口不关闭之后所有 Git 操作都不需要再输 passphrase。关掉窗口再打开重新执行ssh-add一次即可。也可以把eval $(ssh-agent -s)和ssh-add写进~/.bashrc这样每次打开 Git Bash 自动加载但有一说一我对把 ssh-add 写进 bashrc 是持保留态度的因为你每次开窗口都会被要求输入一次 passphrase反而比按需手动ssh-add更烦。按需添加是我目前觉得最舒服的方式。如果想彻底不用输 passphrase 也不设密码短语也不是不行但前提是你得保证电脑本身的安全性比如开启了 Windows Hello 登录、磁盘加密否则私钥文件被提取出去就直接裸奔了。6. 换上 SSH 之后连接失败这类坑我给你趟一遍这部分是我实际被问得最多的地方。前几步看着都做对了但ssh -T gitgithub.com就是报错。我把高频问题按排查链路的顺序整理一下按顺序自查多数人能自己解决。6.1 Permission denied (publickey)八成是密钥没配对或者配对错了这个报错是 SSH 认证失败的经典提示。英文大意为服务器用你提供的公钥和你本地的私钥配对失败。排查链路是这样走的第一步确认你当前用的私钥是不是生成时那把ssh -vT gitgithub.com加-v参数后 SSH 会打印详细连接过程其中有一行Offering public key: ...可以看到实际提交给服务器验证的是哪个公钥。如果它显示的是其他密钥说明~/.ssh/config里指定错了路径或者默认文件名不是id_ed25519。第二步确认公钥确实添加到了平台上。回到 GitHub/Gitee 设置页把页面上的公钥串和本机的.pub文件内容仔细比对尤其是末尾的邮箱注释。很多时候是复制时多了一个空格或者少了一个前缀。第三步如果用的是多密钥场景检查 config 文件里的IdentityFile是否指向了正确的私钥host 名是否和远程地址完全一致。6.2 Host key verification failed要么换了服务器要么第一次连接时手滑了这个报错和刚才的 publickey 完全不同。它发生在最早期SSH 每次连接新服务器时会把服务器的公钥指纹记录下来存到~/.ssh/known_hosts文件里下次连接时再比对防止中间人攻击。如果服务器的 host key 变了比如平台迁移、容器重建或者 known_hosts 里之前记录过不同的指纹就会报这个错。解决方法有两种ssh-keygen -R github.com这一条删除 known_hosts 里 github.com 对应的旧记录再重新ssh -T gitgithub.com会重新提示你确认 host key输入yes保存即可。或者直接手动编辑~/.ssh/known_hosts找到对应行删掉。6.3 Connection timed out 与 Connection refused先别急着怀疑密钥如果错误是Connection timed out连接超时而不是权限问题那和密钥无关问题出在网络通路上。排查顺序先ping github.com看通不通然后再用ssh -vT看卡在哪一步。有时候是公司内网防火墙屏蔽了 SSH 端口22这种情况你可能需要用 SSH over HTTPS 端口443的方式连。GitHub 官方支持这个方案在~/.ssh/config里加Host github.com HostName ssh.github.com Port 443 User git这是 GitHub 官方推荐的变通方案。注意这里HostName改成了ssh.github.com端口变成 443。改完后ssh -T gitgithub.com再试如果能通过说明你本地的 22 端口确实被网络策略限制了443 端口方案完美绕开。6.4 仓库地址写错导致连接目标不对还有一个很低级但很常见的坑远程地址里把git写成了其他用户名或者把gitgithub.com:后面的路径写错了。检查命令git remote -v如果发现远程地址不是你期望的 SSH 形式用之前讲的git remote set-url origin改正。6.5 VS Code 里连不上远程服务器的问题很多 Windows 开发者会顺便把 VS Code 和 Remote-SSH 插件配起来连接公司的 Linux 服务器写代码。如果你在 Git Bash 里 SSH 连接是通的但 VS Code 连不上大概率是 VS Code 的 SSH 扩展调用的 SSH 客户端和环境和 Git Bash 里调用的不是同一个。解决思路在 VS Code 设置里搜remote.SSH.path把它显式指定为 Git 安装目录下的usr\bin\ssh.exe。这个设置很重要因为 VS Code 在 Windows 上默认找系统 OpenSSH和你的 Git 密钥可能不在一个体系。确认 VS Code 下载安装 Remote-SSH 扩展时用的网络环境正常这个扩展需要在 VS Code 内完成安装。在 VS Code 命令面板执行Remote-SSH: Settings把Config File指向C:\Users\你的用户名\.ssh\config确保 VS Code 能读到你的多密钥配置。VS Code 的坑往往不在联机阶段而在“连上了但扩展无法在远程正常运行”。如果出现提示说某个扩展被禁用因为被定义为在远程扩展主机中运行这通常是扩展本身声明了仅支持远程或仅支持本地去扩展详情页看是否要选 install in SSH host 即可不是环境问题。6.6 改完配置不生效优先怀疑缓存和重开Windows 下配置写完不生效最常见的原因是终端/IDE 是之前打开的环境变量和 ssh-agent 都还是旧状态。所以一个很朴素的排查原则把所有相关程序全关掉重新打开一次。Git Bash、CMD、VS Code 全部退出重进。Windows 的 Shell 不会自动感知.bashrc或环境变量的变更只有重启才能让它重新加载。如果要确定配置文件被正确读取可以在 Git Bash 里手动 source 一次source ~/.bashrc但更彻底的验证方式还是重开窗口。6.7 Git 命令的日常高频操作顺手把最常用的列出来环境配好之后日常开发用得最多的命令其实就那么几条。给刚上手的朋友一次性列全省得到处翻文档git clone gitgithub.com:用户名/仓库.git # 克隆远程仓库 git status # 查看工作区状态 git add . # 把所有改动加入暂存区 git commit -m 提交说明 # 提交到本地仓库 git push origin main # 推送到远程 main 分支 git pull origin main # 拉取远程最新代码 git branch -a # 查看所有分支 git checkout -b feature/xxx # 新建并切换分支 git log --oneline --graph --all # 查看提交历史配合之前配的别名 git lg这些命令不需要背用得多了自然就记住了。关键是把环境和 SSH 链路配好后面的路就顺畅了。最后再分享一个实战中得到的经验配置 SSH 密钥时passphrase 不要嫌麻烦跳过建议设一个强度高、有规律、自己一定记得住的密码短语。我见过太多同事嫌麻烦不设密码短语结果装有私钥文件的电脑被别人摸了一下仓库连同服务器权限一块儿拱手让人。反过来设了密码短语之后只要你自己记得住配合 ssh-agent体验上和没设没任何区别安全性却不是一个级别。另外如果你在重装系统或者换了新电脑记得把~/.ssh目录和~/.gitconfig文件提前备份出来。我给自己的电脑做环境迁移时就是把这俩文件拷到新机器上省掉了重新生成密钥、重新配置 user 信息的所有时间。密钥文件本质是文本文件U盘拷贝完全没问题注意别上传到网盘和代码仓库就行。整个环境的“搬家”工作量其实比你想象中小得多。