尧图网站建设 
不废话直接开整。Git 这玩意儿现在的开发者是真绕不开——写代码要版本管理上 GitHub、Gitee 拉代码要认证就连 VSCode 连远程服务器写代码底层也大概率要跟 SSH 打交道。很多新手在 Windows 上装 Git一路“下一步”点完就以为结束了结果真到用的时候要么提交代码报错要么 SSH 连不上服务器要么克隆仓库卡在认证环节。这篇文章就是把这些事从头到尾捋一遍Git 怎么下载、怎么安装、安装完哪些配置必须做、SSH 密钥怎么生成怎么用以及最常见的报错怎么排查。目标是让一个完全没接触过的小白照着操作也能把整套环境跑通。1. 动手之前先搞懂 Git 和 SSH 到底解决什么问题铺垫太多没意思但有几个概念不提前说清楚后面配置的时候大概率会知其然不知其所以然出了问题也只会瞎试。1.1 Git 不是网盘它是时间机器 多人协作工具很多人第一次接触 Git把它当成 Dropbox、百度网盘一类的东西——以为就是把文件传到云端存起来。这个理解不能说全错但会严重影响后面的使用体验。Git 的核心是版本快照你每次提交commit它就把当前所有文件的状态打成一个快照并且记录这次改动了什么、谁改的、什么时候改的。这样一来你可以随时回退到任何一个历史版本可以对比任意两次改动之间的差异也可以拉出任意一条分支做实验不满意直接丢弃。工作区Working Directory、暂存区Staging Area、本地仓库Local Repository这三个概念是理解 Git 操作的基础。工作区就是你电脑上看得见的文件夹暂存区是提交前的中转站决定哪些改动要进入下一条提交本地仓库则是 Git 真正保存快照的地方。日常操作里git add是把改动放进暂存区git commit是把暂存区固化成本地仓库里的一个版本git push才是把本地版本同步到远程仓库。这套机制决定了 Git 是离线可用的你不需要每次都连服务器才能提交版本所有历史记录都在本地远程服务器只是其中一个交换中心。这也是它和 SVN 这类集中式版本控制系统最本质的区别。1.2 为什么非要配 SSH 密钥Git 操作远程仓库比如 GitHub、Gitee 或者公司内网的 GitLab主流有两种认证方式HTTPS 和 SSH。HTTPS 的方式最直观——每次 push 或 pull 的时候输入账号密码。但问题也很明显频繁输入很烦而且很多平台已经不再支持纯密码认证要求你用 Personal Access Token个人访问令牌代替密码。Token 是一长串随机字符又不好记输错了还得重新生成体验相当糟糕。SSH 的方式则是一次配置永久免密。它基于非对称加密你生成一对密钥一把私钥private key留在自己电脑上一把公钥public key上传到服务器。服务器用公钥加密一段随机信息你的电脑用私钥解密能解开就证明你确实是你。私钥不出本地公钥随便分发安全性比密码高得多也方便得多。所以你会发现几乎所有开发者教程里配置完 Git 的第一件事就是配 SSH 密钥。这是打通 Git 和远程仓库的最后一公里。2. 下载与安装官网、版本选择、安装选项逐项解释Git 在 Windows 上的官方默认实现是Git for Windows它附带了一个完整的模拟环境让你能在 Windows 上使用几乎所有的 Git 命令。注意这不等于Git 只能在 Windows 上这么装只是对于绝大多数 Windows 用户来说这就是最标准、最省心的答案。2.1 下载渠道和版本选择下载地址直接去 Git 官方网站git-scm.com点击首页的 Downloads 按钮页面会自动识别 Windows 系统并给出 64-bit 版本的下载链接。如果自动识别不对可以手动点击 Windows 进入下载页选择对应的版本即可。这里有个细节值得留意官网提供两种安装包形态一种是普通的 Setup .exe 安装包另一种是 Portable 免安装版。我建议普通用户直接选 Setup 版因为它会写入 Windows 的系统环境变量还能在右键菜单里加上 Git Bash Here 和 Open GUI Here 两个入口用起来非常顺手。Portable 版适合想完全绿色化、不往系统里写东西的场景但配置起来徒增麻烦新手不推荐。版本选择方面官网通常会提供 32-bit 和 64-bit 两个版本现在的电脑基本都是 64 位选 64-bit 即可。另外还有一个区分点是最新版和维护版非特殊需求一律用最新版。Git 的版本迭代不太会引入破坏性变更没必要像某些软件一样刻意停留在旧版本。如果你在公司内网或离线环境安装需要提前下载好安装包如果官网访问缓慢可以尝试国内的一些院校镜像或开源镜像站下载但要记得核对文件哈希sha256防止下载到被篡改的安装包。2.2 安装向导里的每个选项都代表什么Git for Windows 的安装界面虽然看起来是一路 Next但中间有几个页面其实很关键选错了后面会踩很多坑。我挑几个重点选项说一下。选择组件Select Components页面默认选项基本够用但建议确保这几项是勾选的Git Bash Here在文件夹右键菜单中加入 Git Bash 入口。这是 Windows 下使用 Git 最顺手的终端强烈建议保留。Git GUI Here右键菜单里加入图形界面入口。虽然大多数人用命令行但应急查看历史记录还是挺方便的。Associate .gitconfiguration files with the default text editor*把 .git 开头的配置文件比如 .gitignore、.gitattributes与文本编辑器关联双击就能打开编辑方便。Check daily for Git for Windows updates定期检查更新可以开着不影响日常使用。还有一项 Enable symbolic links启用符号链接圆括号里写着 requires the SeCreateSymbolicLink permission。这个选项不是必需的而且开启后会遇到权限问题建议保持默认不勾选。选择默认编辑器Choosing the default editor used by Git页面默认选项是 Vim。如果你对 Vim 不熟悉强烈建议在这里选择 Use Visual Studio Code as Gits default editor前提是你已经安装过 VSCode或者选 Use Notepad。否则提交的时候不小心进到 Vim 界面你会觉得 Git 卡死了其实是一堆人不知道按i进入编辑模式、按Esc再输入:wq保存退出硬生生把自己卡在 Vim 里气得直接关终端。调整 PATH 环境变量Adjusting your PATH environment页面三个选项Use Git from Git Bash only只在 Git Bash 里能用 Git 命令Windows 自带的 CMD/PowerShell 里用不了。Git from the command line and also from 3rd-party software把 Git 加入系统 PATHCMD、PowerShell、VSCode 终端里都能直接用git命令。这是最推荐的选择也是默认选择。Use Git and optional Unix tools from the Command Prompt把 Git 附带的 Unix 工具也加入 PATH比如bash、sh、cat等。不建议选这个因为会和 Windows 自带的同名命令冲突造成一些莫名其妙的问题。选择 HTTPS 传输后端Choosing the HTTPS transport backend页面默认选项是 Use the OpenSSL library。这个保持默认即可。另一个选项是 Windows 自带的证书库很少被用到而且经常因为企业内网证书问题导致 SSL 报错。配置换行符转换Configuring the line ending conversions页面这是新手最容易踩坑的地方之一我单开一节详细说。安装时默认选第一个 Checkout Windows-style, commit Unix-style line endings 就行但这只是默认值真正决定行为的是安装后git config core.autocrlf的设置后面细讲。2.3 装完后先验证一下安装完成后按下Win R输入cmd回车打开命令提示符或者直接打开 PowerShell输入git --version能输出类似git version 2.47.1.windows.1这样的结果说明安装成功且 PATH 配置正确。再输入git config --list --show-origin这条命令会列出 Git 当前生效的所有配置项以及每条配置的来源文件路径。如果这里能正常输出说明 Git 的核心已经跑通了。顺手再检查一个细节在任意文件夹空白处点右键菜单里应该能看到 Open Git Bash Here 和 Open Git GUI Here 两个选项。如果没有大概率是安装时把组件勾选去掉了回头重新运行安装包选择 Modify 补装即可。3. Git 环境配置用户名、换行符、编辑器一个都不能少安装完成只是第一步接下来这几项配置是必做项。不做的后果一开始可能看不出来等到第一次 push 代码到远程仓库就会发现提交记录里的作者信息是一串乱码一样的默认值或者打开仓库看到满屏的红色告警。3.1 设置提交身份user.name 和 user.emailGit 的每次提交都会记录作者信息这个信息不是从系统自动读取的而是纯靠user.name和user.email两个配置项。如果在提交之前没设置Git 会强行弹出一个编辑器让你补填很多人就是在这里卡住的。打开终端执行git config --global user.name 你的名字 git config --global user.email 你的邮箱注意几个细节--global表示全局生效作用于当前 Windows 用户的所有仓库。如果你不想要全局配置想每个仓库单独设置可以去掉--global进入对应仓库目录后再执行一次。邮箱不一定要用注册 GitHub 的邮箱但建议用同一个这样提交记录能正确关联到你的平台账号。GitHub 后来也允许设置 noreply 邮箱来隐藏真实邮箱但那是后话。配置完之后可以用git config --global --list确认一下是否写对。这套配置的优先级是系统级system 全局级global 仓库级local后写的覆盖先写的。当你遇到我明明设置了用户名怎么提交记录还是显示别人这种诡异问题时十有八九是某个仓库里有更高优先级的 local 配置把全局配置盖掉了。3.2 换行符是新手最大的暗坑Windows 和 Unix/Linux 系系统对文本文件的换行符处理不一样Windows 用CRLF回车 换行Linux/macOS 用LF仅换行。Git 默认在 Windows 上检出checkout代码时把换行符转成CRLF提交commit时再转回LF这就是安装时那个默认选项的意思。这个设计的初衷是好的让 Windows 用户打开文件不出现奇怪的^M符号同时保证仓库里存的是统一的LF。但问题来了如果一个文件本来在仓库里是LF你在 Windows 上修改后用CRLF提交Git 会认为整个文件的每一行都变了——因为每一行的行尾都不一样了。结果就是git diff显示整个文件被改动review 代码的人想骂人合代码的人也容易一脸懵。处理方式分几步确认 autocrlf 状态。执行git config core.autocrlf在 Windows 上默认是true。如果想看全局配置用git config --global core.autocrlf。决定策略。如果你的项目只在 Windows 上开发所有同事都是 Windows 用户直接策略是设置git config --global core.autocrlf false让 Git 不做任何转换仓库里是什么样就什么样。如果你的项目要跨平台协作比如有人用 macOS/Linux更推荐在仓库根目录添加一个.gitattributes文件显式指定哪些文件用什么行尾。例如* textauto *.js text eollf *.py text eollf *.bat text eolcrlf.gitattributes写清楚之后Git 会严格按照文件规则处理不再依赖每台机器上的core.autocrlf设置这才是跨平台协作的正解。修复已有仓库。如果你已经不小心把CRLF提交进仓库了可以执行git add --renormalize . git commit -m Normalize line endings这个命令会根据当前.gitattributes或core.autocrlf规则把仓库里所有文件的换行符重新规范一遍生成一条专门的提交记录。之后大家的基线就统一了。3.3 默认编辑器、大小写敏感与常用别名换行符弄完还有几个零零散散但实际很常用的配置。默认编辑器。如果你安装 Git 时选的不是 VSCode后面想改可以用git config --global core.editor code --wait前提是 VSCode 已经加入系统 PATH 才认code命令。设完之后每次需要 Git 弹出编辑器写提交信息比如git commit不带-m时都会自动打开 VSCode 让你写写完关掉标签页就算确认提交。文件大小写敏感。Windows 文件系统默认大小写不敏感但 Git 是大小写敏感的。这意味着你把Readme.md改成README.mdGit 可能不会自动识别这是一次重命名。正确做法是分两步git mv Readme.md README.md或者强制改git config core.ignorecase false不过这个配置改起来容易引起其他问题建议只在需要重命名文件时用git mv手动处理不要把ignorecase全局改成false。常用别名。Git 支持给命令设置别名减少重复输入。比如git config --global alias.st status git config --global alias.co checkout git config --global alias.cm commit -m git config --global alias.lg log --oneline --graph --all --decorate配完后git st等于git statusgit lg能输出一棵漂亮的提交历史树日常用起来体验提升非常明显。4. SSH 密钥从生成到验证一步步打通免密登录配置到这里Git 本身已经能用了但和远程仓库的交互还没打通。接下来就是整个教程的重头戏SSH 密钥的生成与配置。这一步做完git clone、git push、git pull这些操作就不再需要每次输入用户名密码或 Token 了。4.1 生成密钥前先想清楚的两个问题第一用哪种算法目前推荐用 Ed25519。它的密钥更短、生成更快、安全性也足够而且是 OpenSSH 从版本 6.5 开始就支持的算法。GitHub、Gitee 这些主流平台都支持它。如果你需要兼容非常老旧的服务器比如还在用 OpenSSH 6.4 以下版本的系统才考虑用 RSA。RSA 密钥生成时建议把位数设为 4096ssh-keygen -t rsa -b 4096 -C 你的邮箱或备注第二密钥放在哪里、叫什么名字默认存放路径是C:\Users\你的用户名\.ssh\id_ed25519或id_rsa。如果你只有一台电脑、一个常用平台账号直接用默认路径和默认文件名就行可以少踩很多配置文件相关的坑。如果你有多个平台的多个账号需要给不同密钥起不同的名字比如github_work、gitee_personal、company_server这部分我在第 5 节详细讲。4.2 正式生成算法、注释、密码短语打开Git Bash务必用 Git Bash不要用 CMD 或 PowerShell因为后面会用到一些 Unix 命令执行ssh-keygen -t ed25519 -C 你的邮箱或备注敲回车后系统会问你要把密钥保存在哪个文件Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):直接回车使用默认路径即可。接着会问你是否设置 passphrase密码短语Enter passphrase (empty for no passphrase):这里有两个选择直接回车留空免密使用私钥一旦泄露别人就能直接使用它。但对个人本地电脑来说方便性优先。设置一个 passphrase每次使用私钥时都要输入一次。如果配合 ssh-agent 使用只需要在会话开始时输入一次之后都不用重复输。我更推荐的组合是设置一个 passphrase然后启用 ssh-agent 记住解锁状态。这样既安全又不用反复输入。关于 ssh-agent 的启用见 4.4 节。生成完成后.ssh目录下会出现两个文件id_ed25519私钥绝对不能泄露谁拿到它谁就能冒充你。id_ed25519.pub公钥可以安全地提交给服务器或托管平台。查看公钥内容用cat ~/.ssh/id_ed25519.pub输出是一行以ssh-ed25519 AAAA...开头的字符串这就是待会要添加到平台的内容。4.3 把公钥交给 GitHub / Gitee公钥生成的下一步是把公钥内容添加到你要用的代码托管平台。不同平台入口大同小异这里以 GitHub 为例登录 GitHub点击右上角头像 → Settings。左侧菜单找到SSH and GPG keys。点击New SSH key按钮。Title 随便填一个能区分用途的名字比如 My Windows PC 或 Home Desktop。Key type 保持默认的Authentication Key。把.pub文件里的内容完整复制粘贴到 Key 输入框里。注意整段都要复制不要加空格、不要换行、不要少字符。点击Add SSH key确认。Gitee码云的路径类似设置 → SSH 公钥 → 添加公钥。GitLab 也差不多Preferences → SSH Keys。公司自建的 GitLab 通常是经过管理员限制的如果上传公钥的地方找不到找管理员要入口即可。4.4 测试连接与 ssh-agent公钥添加完成后在 Git Bash 里测试一下ssh -T gitgithub.com如果看到Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.说明密钥认证成功SSH 通道已经打通了。如果是 Gitee命令是ssh -T gitgitee.com成功提示类似。这里有个小知识点SSH 默认的端口是 22。如果你的网络环境里 22 端口不通企业防火墙、校园网之类可以改用 443 端口连接 GitHub需要修改~/.ssh/config文件这部分放到第 5 节一起说因为和 config 文件的写法强相关。ssh-agent 是干什么的简单说它是一个在后台运行的小程序负责保存你解锁过的私钥让其他 SSH 连接直接复用不用反复输入 passphrase。Windows 自带的 OpenSSH 服务可以作为 ssh-agent 使用但 Git for Windows 也有自己的 agent 实现。为了让它更好用建议在 Git Bash 里执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519首次执行ssh-add时输入私钥 passphrase之后在当前的 Git Bash 会话里所有 SSH 连接都不需要再输入 passphrase。不想每次打开 Git Bash 都手动执行eval $(ssh-agent -s)的可以直接在 Windows 的服务services.msc里找到OpenSSH Authentication Agent把启动类型改成自动然后启动它。再把ssh-add ~/.ssh/id_ed25519加到你常用的 shell 启动脚本里比如~/.bashrc或~/.profile。这样每次打开终端agent 自动运行、秘钥自动加载体验最流畅。5. 多账号场景一台电脑同时管理 GitHub、Gitee、公司服务器的密钥配置很多人实际使用中会碰到这种情况一个 GitHub 个人账号一个 Gitee 账号因为国内访问快或者公司项目在上面还有一台公司的 GitLab 服务器。这些平台上的账号邮箱都不一样如果你还沿用默认的id_ed25519一个密钥走天下服务器那边肯定会有冲突。单看某个平台没问题但多个平台各传一次同一个公钥一旦某个平台那边出了状况或者你想撤销某个平台的访问权限就得把所有平台全部重来一遍。更好的做法是分平台生成不同的密钥然后通过~/.ssh/config文件告诉 SSH 客户端哪个域名用哪把密钥。5.1 什么时候需要多密钥我总结一下出现下面任一情况就说明你需要考虑多密钥方案了你在两个不同的代码托管平台都有账号且邮箱不同。比如 GitHub 用私人邮箱公司 GitLab 用公司邮箱。你对不同项目希望使用不同的提交身份。比如个人开源项目和公司商业项目要严格区分。你的公司安全策略要求每个系统使用独立密钥或者要求定期轮换密钥共用一把私钥会觉得很不稳妥。5.2 config 文件的写法与含义多密钥的核心是一个配置文件~/.ssh/config。这个文件默认不存在需要手动创建。在 Git Bash 里执行touch ~/.ssh/config然后打开编辑推荐用 VSCode 或 Notepadcode ~/.ssh/config写入如下格式的内容# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes # Gitee Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes # 公司 GitLab Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company IdentitiesOnly yes这里解释一下几个关键字段Host你在 SSH 命令和 Git remote 地址里使用的别名。它可以和真实域名一样如github.com也可以设置成自定义短名如gh。如果设置了自定义短名远程仓库地址要相应修改比如gitgh:用户名/仓库名.git。HostName真实的服务器地址。UserSSH 登录用户名。对 GitHub/Gitee/GitLab 这些平台来说固定是git不用改。IdentityFile指定使用哪个私钥文件。IdentitiesOnly yes强制 SSH 只使用这里指定的私钥不要尝试~/.ssh/id_ed25519或其他默认密钥。不加这一项SSH 会先把默认密钥全部试一遍如果数量多认证会变慢还可能出现尝试了错误的密钥导致被服务器拒绝这种隐性问题。在这之前你还需要为不同平台生成不同命名的密钥。比如ssh-keygen -t ed25519 -C github_emailexample.com -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C gitee_emailexample.com -f ~/.ssh/id_ed25519_gitee-f参数用于指定保存路径和文件名。生成之后把对应.pub内容分别添加到对应平台即可。配置完成后测试一下ssh -T gitgithub.com ssh -T gitgitee.com正常情况下两条命令会分别显示你添加对应公钥时关联的用户名。每条连接都会按config文件里的 Host 精确匹配使用对应的私钥。如果遇到config文件不生效的情况先检查文件权限。Windows 的 OpenSSH 对 config 文件权限有严格的要求过宽的权限可能导致它被忽略。在 Git Bash 里可以执行ls -l ~/.ssh/config如果文件权限太开放比如 Everyone 有读权限可以在文件属性的安全设置里收紧权限只保留当前用户的读写权限。Git Bash 里也可以直接用chmod 600 ~/.ssh/config试试某些场景下有效。还有一个进阶需求连接 GitHub 时通过走 443 端口而不是默认的 22 端口。格式是Host github.com HostName ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes注意这里的 HostName 变成了ssh.github.com端口是 443。之后git clone gitgithub.com:用户/仓库.git这种地址不需要改SSH 会依据 Host 匹配到这段配置。5.3 仓库地址和 remote 怎么改SSH 配置完成之后你之前用 HTTPS 方式克隆的仓库remote 地址仍停留在https://github.com/xxx/xxx.git形式不会自动切换。要么改用 SSH 地址重新克隆要么手动修改现有仓库的 remotegit remote set-url origin gitgithub.com:用户名/仓库名.git或者直接编辑.git/config文件把url 那一行替换成 SSH 格式。判断当前仓库用的是哪个协议用git remote -v输出里https://开头就是 HTTPS 协议git开头则是 SSH 协议。多账号场景下尤其要注意 remote 地址里的 Host 是否和config文件里定义的 Host 保持一致否则匹配不上私钥会一直报 Permission denied。5.4 多账号踩坑记录配置多账号的时候我踩过几个坑写出来给大家提个醒。第一个坑是公钥上传到了错误的平台。A 平台的公钥文件复制到了 B 平台的设置页面上看起来都是类似ssh-ed25519 AAAA...的格式不仔细看根本分辨不出来。而且保存后平台也不会校验这公钥是否已经其他平台在用所以经常出现公钥添加成功了但认证总失败的情况。解决方法是在.pub文件的末尾会有你生成时填写的-C注释邮箱或备注对照一下平台上的收录记录或者直接重新生成并重新上传。第二个坑是本地存在多个 key 时SSH 使用了错误的那个。SSH 的密钥选择逻辑是先看config文件再看默认路径。如果你没有写config或者写了但IdentitiesOnly没有加SSH 可能会先把默认的id_ed25519如果存在发给服务器服务器说不识别这个 key它才尝试下一个。如果服务器有连接失败次数限制试两三次就被封 IP 或者要求等一会儿了。这也是为什么我反复强调IdentitiesOnly yes一定要写。第三个坑是passphrase 忘记了。私钥本身设置了 passphrase但一旦忘记没有任何找回手段只能重新生成密钥、重新上传公钥、重新配置远程仓库。相比之下公钥可以随便公开重新生成之后旧公钥作废即可。所以设置 passphrase 前建议自己评估一下安全性收益和丢失成本设置完之后可以用密码管理器存好。6. 高频命令与疑难报错排查速查环境配置讲得差不多了最后这部分是查字典环节。我按实际使用频率整理了一份命令速查表和一份报错排查清单遇到问题直接翻到这里对照。6.1 日常开发高频命令一张表操作场景命令说明克隆仓库git clone gitgithub.com:用户/仓库.gitHHTP 地址也能克隆但 SSH 更顺手查看状态git status显示工作区当前变更查看差异git diff查看未暂存的具体改动添加改动git add .暂存所有改动git add 文件名只暂存指定文件提交git commit -m 提交说明-m直接跟说明文字否则会打开编辑器推送git push首次推送指定远端分支git push -u origin main拉取git pull相当于git fetchgit merge查看历史git log --oneline --graph一行一条提交记录配合图表更直观切换分支git switch 分支名新版本推荐用switch替代checkout创建分支git switch -c 新分支名新建并切换合并分支git merge 分支名把指定分支合入当前分支暂存现场git stash存到一边回来用git stash pop回滚未提交改动git restore 文件名丢弃工作区修改谨慎操作撤销上一次提交git reset --soft HEAD~1--soft保留改动--hard会彻底丢弃这些命令没要求大家背下来但建议在理解原理的基础上多用几次。比如git add到git commit到git push这条链路其实对应的是工作区 → 暂存区 → 本地仓库 → 远程仓库四个层级的流转。概念立得住命令就不会乱。6.2 高频报错Permission deniedpublickey怎么查遇到最多的报错就是类似gitgithub.com: Permission denied (publickey). fatal: Could not read from remote repository.很多人第一反应是是不是我密码错了其实不是这个报错说明 SSH 密钥认证环节失败了。按这个顺序排查先确认 ssh-agent 里有没有加载正确的私钥。执行ssh-add -l如果有输出看是否包含你预期的那把 key 的指纹。没有的话执行ssh-add ~/.ssh/对应私钥文件。确认config文件是否匹配到了正确的 Host 和 IdentityFile。可以加-v参数看详细日志ssh -vT gitgithub.com日志里会输出尝试了哪些私钥文件。确认公钥是否确实添加到了平台。打开平台设置页和本地.pub文件逐字符核对。如果用的是公司 GitLab有时候是账号被禁用或未审核联系管理员确认。一个非常隐蔽的坑是Windows 上如果同时装了 Git for Windows 和 Windows 自带的 OpenSSHssh命令可能指向了不同的实现导致读到的~/.ssh路径不一样。Git for Windows 的 HOME 通常是C:\Users\用户名但有些工具会把 HOME 指到别处。排查方式是在 Git Bash 里执行echo $HOME看看路径是否如预期。6.3 其他三个高频坑换行、合并、分支名报错一LF will be replaced by CRLF这个告警不是错误不会阻断操作。它只是告诉你 Git 正在按照 autocrlf 规则转换换行符。如果这个提示反复出现且影响 diff 阅读回到 3.2 节把.gitattributes配置起来一劳永逸。报错二fatal: refusing to merge unrelated histories这个报错常见于两个仓库没有共同的历史基础比如你在 GitHub 上新建了一个仓库但初始化了 README本地又init了一个仓库两边历史互不相干直接pull就会报这个错。解决办法是显式允许不相关历史合并git pull origin main --allow-unrelated-histories但要注意这个操作会把两个完全不同历史合并到一起之后可能产生大量冲突建议先想清楚是不是有更合理的流程比如直接重新克隆。报错三src refspec main does not match any这个报错通常说明你还没有创建本地提交或者当前分支名不是main但推送时指定了main。解决办法是先写一个提交或者看下当前分支名再推送git branch -M main git push -u origin maingit branch -M main是把当前分支重命名为main如果你本地确实叫master也可以用这条命令统一命名。另外还有一个经常出现的提醒fatal: could not read Username for https://github.com。这个报错几乎可以断定是用 HTTPS 协议访问远程仓库时没有正确配置凭据或者凭据过期了。最简单的解决方式是把 remote 地址改成 SSH 格式参考 5.3 节。如果你确实想继续用 HTTPS可以在 Windows 凭据管理器Credential Manager里找到旧的凭据删掉下次 push 时重新输入账号密码或 Token。个人经验到最后说一句Git 和 SSH 这套东西刚开始接触会觉得概念多、命令杂、配置文件又长但真正常用的其实就那么几条命令加一个配置文件。与其把文档从头到尾背一遍不如把本文提到的配置流程完整走一遍然后找个真实的项目练手克隆、修改、提交、推送、分支合并各来一轮。踩过两三个坑之后你会发现自己对这些玄学问题基本都能独立定位了。如果后续碰到更刁钻的场景比如 Windows 上 Git 命令在 PowerShell 里的兼容问题、大规模仓库的稀疏检出sparse checkout、或者 Git LFS 大文件存储也可以顺着今天搭好的环境继续往下探索。先把地基打稳剩下的都好说。 Windows下Git安装配置与SSH密钥完整指南
不废话直接开整。Git 这玩意儿现在的开发者是真绕不开——写代码要版本管理上 GitHub、Gitee 拉代码要认证就连 VSCode 连远程服务器写代码底层也大概率要跟 SSH 打交道。很多新手在 Windows 上装 Git一路“下一步”点完就以为结束了结果真到用的时候要么提交代码报错要么 SSH 连不上服务器要么克隆仓库卡在认证环节。这篇文章就是把这些事从头到尾捋一遍Git 怎么下载、怎么安装、安装完哪些配置必须做、SSH 密钥怎么生成怎么用以及最常见的报错怎么排查。目标是让一个完全没接触过的小白照着操作也能把整套环境跑通。1. 动手之前先搞懂 Git 和 SSH 到底解决什么问题铺垫太多没意思但有几个概念不提前说清楚后面配置的时候大概率会知其然不知其所以然出了问题也只会瞎试。1.1 Git 不是网盘它是时间机器 多人协作工具很多人第一次接触 Git把它当成 Dropbox、百度网盘一类的东西——以为就是把文件传到云端存起来。这个理解不能说全错但会严重影响后面的使用体验。Git 的核心是版本快照你每次提交commit它就把当前所有文件的状态打成一个快照并且记录这次改动了什么、谁改的、什么时候改的。这样一来你可以随时回退到任何一个历史版本可以对比任意两次改动之间的差异也可以拉出任意一条分支做实验不满意直接丢弃。工作区Working Directory、暂存区Staging Area、本地仓库Local Repository这三个概念是理解 Git 操作的基础。工作区就是你电脑上看得见的文件夹暂存区是提交前的中转站决定哪些改动要进入下一条提交本地仓库则是 Git 真正保存快照的地方。日常操作里git add是把改动放进暂存区git commit是把暂存区固化成本地仓库里的一个版本git push才是把本地版本同步到远程仓库。这套机制决定了 Git 是离线可用的你不需要每次都连服务器才能提交版本所有历史记录都在本地远程服务器只是其中一个交换中心。这也是它和 SVN 这类集中式版本控制系统最本质的区别。1.2 为什么非要配 SSH 密钥Git 操作远程仓库比如 GitHub、Gitee 或者公司内网的 GitLab主流有两种认证方式HTTPS 和 SSH。HTTPS 的方式最直观——每次 push 或 pull 的时候输入账号密码。但问题也很明显频繁输入很烦而且很多平台已经不再支持纯密码认证要求你用 Personal Access Token个人访问令牌代替密码。Token 是一长串随机字符又不好记输错了还得重新生成体验相当糟糕。SSH 的方式则是一次配置永久免密。它基于非对称加密你生成一对密钥一把私钥private key留在自己电脑上一把公钥public key上传到服务器。服务器用公钥加密一段随机信息你的电脑用私钥解密能解开就证明你确实是你。私钥不出本地公钥随便分发安全性比密码高得多也方便得多。所以你会发现几乎所有开发者教程里配置完 Git 的第一件事就是配 SSH 密钥。这是打通 Git 和远程仓库的最后一公里。2. 下载与安装官网、版本选择、安装选项逐项解释Git 在 Windows 上的官方默认实现是Git for Windows它附带了一个完整的模拟环境让你能在 Windows 上使用几乎所有的 Git 命令。注意这不等于Git 只能在 Windows 上这么装只是对于绝大多数 Windows 用户来说这就是最标准、最省心的答案。2.1 下载渠道和版本选择下载地址直接去 Git 官方网站git-scm.com点击首页的 Downloads 按钮页面会自动识别 Windows 系统并给出 64-bit 版本的下载链接。如果自动识别不对可以手动点击 Windows 进入下载页选择对应的版本即可。这里有个细节值得留意官网提供两种安装包形态一种是普通的 Setup .exe 安装包另一种是 Portable 免安装版。我建议普通用户直接选 Setup 版因为它会写入 Windows 的系统环境变量还能在右键菜单里加上 Git Bash Here 和 Open GUI Here 两个入口用起来非常顺手。Portable 版适合想完全绿色化、不往系统里写东西的场景但配置起来徒增麻烦新手不推荐。版本选择方面官网通常会提供 32-bit 和 64-bit 两个版本现在的电脑基本都是 64 位选 64-bit 即可。另外还有一个区分点是最新版和维护版非特殊需求一律用最新版。Git 的版本迭代不太会引入破坏性变更没必要像某些软件一样刻意停留在旧版本。如果你在公司内网或离线环境安装需要提前下载好安装包如果官网访问缓慢可以尝试国内的一些院校镜像或开源镜像站下载但要记得核对文件哈希sha256防止下载到被篡改的安装包。2.2 安装向导里的每个选项都代表什么Git for Windows 的安装界面虽然看起来是一路 Next但中间有几个页面其实很关键选错了后面会踩很多坑。我挑几个重点选项说一下。选择组件Select Components页面默认选项基本够用但建议确保这几项是勾选的Git Bash Here在文件夹右键菜单中加入 Git Bash 入口。这是 Windows 下使用 Git 最顺手的终端强烈建议保留。Git GUI Here右键菜单里加入图形界面入口。虽然大多数人用命令行但应急查看历史记录还是挺方便的。Associate .gitconfiguration files with the default text editor*把 .git 开头的配置文件比如 .gitignore、.gitattributes与文本编辑器关联双击就能打开编辑方便。Check daily for Git for Windows updates定期检查更新可以开着不影响日常使用。还有一项 Enable symbolic links启用符号链接圆括号里写着 requires the SeCreateSymbolicLink permission。这个选项不是必需的而且开启后会遇到权限问题建议保持默认不勾选。选择默认编辑器Choosing the default editor used by Git页面默认选项是 Vim。如果你对 Vim 不熟悉强烈建议在这里选择 Use Visual Studio Code as Gits default editor前提是你已经安装过 VSCode或者选 Use Notepad。否则提交的时候不小心进到 Vim 界面你会觉得 Git 卡死了其实是一堆人不知道按i进入编辑模式、按Esc再输入:wq保存退出硬生生把自己卡在 Vim 里气得直接关终端。调整 PATH 环境变量Adjusting your PATH environment页面三个选项Use Git from Git Bash only只在 Git Bash 里能用 Git 命令Windows 自带的 CMD/PowerShell 里用不了。Git from the command line and also from 3rd-party software把 Git 加入系统 PATHCMD、PowerShell、VSCode 终端里都能直接用git命令。这是最推荐的选择也是默认选择。Use Git and optional Unix tools from the Command Prompt把 Git 附带的 Unix 工具也加入 PATH比如bash、sh、cat等。不建议选这个因为会和 Windows 自带的同名命令冲突造成一些莫名其妙的问题。选择 HTTPS 传输后端Choosing the HTTPS transport backend页面默认选项是 Use the OpenSSL library。这个保持默认即可。另一个选项是 Windows 自带的证书库很少被用到而且经常因为企业内网证书问题导致 SSL 报错。配置换行符转换Configuring the line ending conversions页面这是新手最容易踩坑的地方之一我单开一节详细说。安装时默认选第一个 Checkout Windows-style, commit Unix-style line endings 就行但这只是默认值真正决定行为的是安装后git config core.autocrlf的设置后面细讲。2.3 装完后先验证一下安装完成后按下Win R输入cmd回车打开命令提示符或者直接打开 PowerShell输入git --version能输出类似git version 2.47.1.windows.1这样的结果说明安装成功且 PATH 配置正确。再输入git config --list --show-origin这条命令会列出 Git 当前生效的所有配置项以及每条配置的来源文件路径。如果这里能正常输出说明 Git 的核心已经跑通了。顺手再检查一个细节在任意文件夹空白处点右键菜单里应该能看到 Open Git Bash Here 和 Open Git GUI Here 两个选项。如果没有大概率是安装时把组件勾选去掉了回头重新运行安装包选择 Modify 补装即可。3. Git 环境配置用户名、换行符、编辑器一个都不能少安装完成只是第一步接下来这几项配置是必做项。不做的后果一开始可能看不出来等到第一次 push 代码到远程仓库就会发现提交记录里的作者信息是一串乱码一样的默认值或者打开仓库看到满屏的红色告警。3.1 设置提交身份user.name 和 user.emailGit 的每次提交都会记录作者信息这个信息不是从系统自动读取的而是纯靠user.name和user.email两个配置项。如果在提交之前没设置Git 会强行弹出一个编辑器让你补填很多人就是在这里卡住的。打开终端执行git config --global user.name 你的名字 git config --global user.email 你的邮箱注意几个细节--global表示全局生效作用于当前 Windows 用户的所有仓库。如果你不想要全局配置想每个仓库单独设置可以去掉--global进入对应仓库目录后再执行一次。邮箱不一定要用注册 GitHub 的邮箱但建议用同一个这样提交记录能正确关联到你的平台账号。GitHub 后来也允许设置 noreply 邮箱来隐藏真实邮箱但那是后话。配置完之后可以用git config --global --list确认一下是否写对。这套配置的优先级是系统级system 全局级global 仓库级local后写的覆盖先写的。当你遇到我明明设置了用户名怎么提交记录还是显示别人这种诡异问题时十有八九是某个仓库里有更高优先级的 local 配置把全局配置盖掉了。3.2 换行符是新手最大的暗坑Windows 和 Unix/Linux 系系统对文本文件的换行符处理不一样Windows 用CRLF回车 换行Linux/macOS 用LF仅换行。Git 默认在 Windows 上检出checkout代码时把换行符转成CRLF提交commit时再转回LF这就是安装时那个默认选项的意思。这个设计的初衷是好的让 Windows 用户打开文件不出现奇怪的^M符号同时保证仓库里存的是统一的LF。但问题来了如果一个文件本来在仓库里是LF你在 Windows 上修改后用CRLF提交Git 会认为整个文件的每一行都变了——因为每一行的行尾都不一样了。结果就是git diff显示整个文件被改动review 代码的人想骂人合代码的人也容易一脸懵。处理方式分几步确认 autocrlf 状态。执行git config core.autocrlf在 Windows 上默认是true。如果想看全局配置用git config --global core.autocrlf。决定策略。如果你的项目只在 Windows 上开发所有同事都是 Windows 用户直接策略是设置git config --global core.autocrlf false让 Git 不做任何转换仓库里是什么样就什么样。如果你的项目要跨平台协作比如有人用 macOS/Linux更推荐在仓库根目录添加一个.gitattributes文件显式指定哪些文件用什么行尾。例如* textauto *.js text eollf *.py text eollf *.bat text eolcrlf.gitattributes写清楚之后Git 会严格按照文件规则处理不再依赖每台机器上的core.autocrlf设置这才是跨平台协作的正解。修复已有仓库。如果你已经不小心把CRLF提交进仓库了可以执行git add --renormalize . git commit -m Normalize line endings这个命令会根据当前.gitattributes或core.autocrlf规则把仓库里所有文件的换行符重新规范一遍生成一条专门的提交记录。之后大家的基线就统一了。3.3 默认编辑器、大小写敏感与常用别名换行符弄完还有几个零零散散但实际很常用的配置。默认编辑器。如果你安装 Git 时选的不是 VSCode后面想改可以用git config --global core.editor code --wait前提是 VSCode 已经加入系统 PATH 才认code命令。设完之后每次需要 Git 弹出编辑器写提交信息比如git commit不带-m时都会自动打开 VSCode 让你写写完关掉标签页就算确认提交。文件大小写敏感。Windows 文件系统默认大小写不敏感但 Git 是大小写敏感的。这意味着你把Readme.md改成README.mdGit 可能不会自动识别这是一次重命名。正确做法是分两步git mv Readme.md README.md或者强制改git config core.ignorecase false不过这个配置改起来容易引起其他问题建议只在需要重命名文件时用git mv手动处理不要把ignorecase全局改成false。常用别名。Git 支持给命令设置别名减少重复输入。比如git config --global alias.st status git config --global alias.co checkout git config --global alias.cm commit -m git config --global alias.lg log --oneline --graph --all --decorate配完后git st等于git statusgit lg能输出一棵漂亮的提交历史树日常用起来体验提升非常明显。4. SSH 密钥从生成到验证一步步打通免密登录配置到这里Git 本身已经能用了但和远程仓库的交互还没打通。接下来就是整个教程的重头戏SSH 密钥的生成与配置。这一步做完git clone、git push、git pull这些操作就不再需要每次输入用户名密码或 Token 了。4.1 生成密钥前先想清楚的两个问题第一用哪种算法目前推荐用 Ed25519。它的密钥更短、生成更快、安全性也足够而且是 OpenSSH 从版本 6.5 开始就支持的算法。GitHub、Gitee 这些主流平台都支持它。如果你需要兼容非常老旧的服务器比如还在用 OpenSSH 6.4 以下版本的系统才考虑用 RSA。RSA 密钥生成时建议把位数设为 4096ssh-keygen -t rsa -b 4096 -C 你的邮箱或备注第二密钥放在哪里、叫什么名字默认存放路径是C:\Users\你的用户名\.ssh\id_ed25519或id_rsa。如果你只有一台电脑、一个常用平台账号直接用默认路径和默认文件名就行可以少踩很多配置文件相关的坑。如果你有多个平台的多个账号需要给不同密钥起不同的名字比如github_work、gitee_personal、company_server这部分我在第 5 节详细讲。4.2 正式生成算法、注释、密码短语打开Git Bash务必用 Git Bash不要用 CMD 或 PowerShell因为后面会用到一些 Unix 命令执行ssh-keygen -t ed25519 -C 你的邮箱或备注敲回车后系统会问你要把密钥保存在哪个文件Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):直接回车使用默认路径即可。接着会问你是否设置 passphrase密码短语Enter passphrase (empty for no passphrase):这里有两个选择直接回车留空免密使用私钥一旦泄露别人就能直接使用它。但对个人本地电脑来说方便性优先。设置一个 passphrase每次使用私钥时都要输入一次。如果配合 ssh-agent 使用只需要在会话开始时输入一次之后都不用重复输。我更推荐的组合是设置一个 passphrase然后启用 ssh-agent 记住解锁状态。这样既安全又不用反复输入。关于 ssh-agent 的启用见 4.4 节。生成完成后.ssh目录下会出现两个文件id_ed25519私钥绝对不能泄露谁拿到它谁就能冒充你。id_ed25519.pub公钥可以安全地提交给服务器或托管平台。查看公钥内容用cat ~/.ssh/id_ed25519.pub输出是一行以ssh-ed25519 AAAA...开头的字符串这就是待会要添加到平台的内容。4.3 把公钥交给 GitHub / Gitee公钥生成的下一步是把公钥内容添加到你要用的代码托管平台。不同平台入口大同小异这里以 GitHub 为例登录 GitHub点击右上角头像 → Settings。左侧菜单找到SSH and GPG keys。点击New SSH key按钮。Title 随便填一个能区分用途的名字比如 My Windows PC 或 Home Desktop。Key type 保持默认的Authentication Key。把.pub文件里的内容完整复制粘贴到 Key 输入框里。注意整段都要复制不要加空格、不要换行、不要少字符。点击Add SSH key确认。Gitee码云的路径类似设置 → SSH 公钥 → 添加公钥。GitLab 也差不多Preferences → SSH Keys。公司自建的 GitLab 通常是经过管理员限制的如果上传公钥的地方找不到找管理员要入口即可。4.4 测试连接与 ssh-agent公钥添加完成后在 Git Bash 里测试一下ssh -T gitgithub.com如果看到Hi 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.说明密钥认证成功SSH 通道已经打通了。如果是 Gitee命令是ssh -T gitgitee.com成功提示类似。这里有个小知识点SSH 默认的端口是 22。如果你的网络环境里 22 端口不通企业防火墙、校园网之类可以改用 443 端口连接 GitHub需要修改~/.ssh/config文件这部分放到第 5 节一起说因为和 config 文件的写法强相关。ssh-agent 是干什么的简单说它是一个在后台运行的小程序负责保存你解锁过的私钥让其他 SSH 连接直接复用不用反复输入 passphrase。Windows 自带的 OpenSSH 服务可以作为 ssh-agent 使用但 Git for Windows 也有自己的 agent 实现。为了让它更好用建议在 Git Bash 里执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519首次执行ssh-add时输入私钥 passphrase之后在当前的 Git Bash 会话里所有 SSH 连接都不需要再输入 passphrase。不想每次打开 Git Bash 都手动执行eval $(ssh-agent -s)的可以直接在 Windows 的服务services.msc里找到OpenSSH Authentication Agent把启动类型改成自动然后启动它。再把ssh-add ~/.ssh/id_ed25519加到你常用的 shell 启动脚本里比如~/.bashrc或~/.profile。这样每次打开终端agent 自动运行、秘钥自动加载体验最流畅。5. 多账号场景一台电脑同时管理 GitHub、Gitee、公司服务器的密钥配置很多人实际使用中会碰到这种情况一个 GitHub 个人账号一个 Gitee 账号因为国内访问快或者公司项目在上面还有一台公司的 GitLab 服务器。这些平台上的账号邮箱都不一样如果你还沿用默认的id_ed25519一个密钥走天下服务器那边肯定会有冲突。单看某个平台没问题但多个平台各传一次同一个公钥一旦某个平台那边出了状况或者你想撤销某个平台的访问权限就得把所有平台全部重来一遍。更好的做法是分平台生成不同的密钥然后通过~/.ssh/config文件告诉 SSH 客户端哪个域名用哪把密钥。5.1 什么时候需要多密钥我总结一下出现下面任一情况就说明你需要考虑多密钥方案了你在两个不同的代码托管平台都有账号且邮箱不同。比如 GitHub 用私人邮箱公司 GitLab 用公司邮箱。你对不同项目希望使用不同的提交身份。比如个人开源项目和公司商业项目要严格区分。你的公司安全策略要求每个系统使用独立密钥或者要求定期轮换密钥共用一把私钥会觉得很不稳妥。5.2 config 文件的写法与含义多密钥的核心是一个配置文件~/.ssh/config。这个文件默认不存在需要手动创建。在 Git Bash 里执行touch ~/.ssh/config然后打开编辑推荐用 VSCode 或 Notepadcode ~/.ssh/config写入如下格式的内容# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes # Gitee Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes # 公司 GitLab Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company IdentitiesOnly yes这里解释一下几个关键字段Host你在 SSH 命令和 Git remote 地址里使用的别名。它可以和真实域名一样如github.com也可以设置成自定义短名如gh。如果设置了自定义短名远程仓库地址要相应修改比如gitgh:用户名/仓库名.git。HostName真实的服务器地址。UserSSH 登录用户名。对 GitHub/Gitee/GitLab 这些平台来说固定是git不用改。IdentityFile指定使用哪个私钥文件。IdentitiesOnly yes强制 SSH 只使用这里指定的私钥不要尝试~/.ssh/id_ed25519或其他默认密钥。不加这一项SSH 会先把默认密钥全部试一遍如果数量多认证会变慢还可能出现尝试了错误的密钥导致被服务器拒绝这种隐性问题。在这之前你还需要为不同平台生成不同命名的密钥。比如ssh-keygen -t ed25519 -C github_emailexample.com -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C gitee_emailexample.com -f ~/.ssh/id_ed25519_gitee-f参数用于指定保存路径和文件名。生成之后把对应.pub内容分别添加到对应平台即可。配置完成后测试一下ssh -T gitgithub.com ssh -T gitgitee.com正常情况下两条命令会分别显示你添加对应公钥时关联的用户名。每条连接都会按config文件里的 Host 精确匹配使用对应的私钥。如果遇到config文件不生效的情况先检查文件权限。Windows 的 OpenSSH 对 config 文件权限有严格的要求过宽的权限可能导致它被忽略。在 Git Bash 里可以执行ls -l ~/.ssh/config如果文件权限太开放比如 Everyone 有读权限可以在文件属性的安全设置里收紧权限只保留当前用户的读写权限。Git Bash 里也可以直接用chmod 600 ~/.ssh/config试试某些场景下有效。还有一个进阶需求连接 GitHub 时通过走 443 端口而不是默认的 22 端口。格式是Host github.com HostName ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes注意这里的 HostName 变成了ssh.github.com端口是 443。之后git clone gitgithub.com:用户/仓库.git这种地址不需要改SSH 会依据 Host 匹配到这段配置。5.3 仓库地址和 remote 怎么改SSH 配置完成之后你之前用 HTTPS 方式克隆的仓库remote 地址仍停留在https://github.com/xxx/xxx.git形式不会自动切换。要么改用 SSH 地址重新克隆要么手动修改现有仓库的 remotegit remote set-url origin gitgithub.com:用户名/仓库名.git或者直接编辑.git/config文件把url 那一行替换成 SSH 格式。判断当前仓库用的是哪个协议用git remote -v输出里https://开头就是 HTTPS 协议git开头则是 SSH 协议。多账号场景下尤其要注意 remote 地址里的 Host 是否和config文件里定义的 Host 保持一致否则匹配不上私钥会一直报 Permission denied。5.4 多账号踩坑记录配置多账号的时候我踩过几个坑写出来给大家提个醒。第一个坑是公钥上传到了错误的平台。A 平台的公钥文件复制到了 B 平台的设置页面上看起来都是类似ssh-ed25519 AAAA...的格式不仔细看根本分辨不出来。而且保存后平台也不会校验这公钥是否已经其他平台在用所以经常出现公钥添加成功了但认证总失败的情况。解决方法是在.pub文件的末尾会有你生成时填写的-C注释邮箱或备注对照一下平台上的收录记录或者直接重新生成并重新上传。第二个坑是本地存在多个 key 时SSH 使用了错误的那个。SSH 的密钥选择逻辑是先看config文件再看默认路径。如果你没有写config或者写了但IdentitiesOnly没有加SSH 可能会先把默认的id_ed25519如果存在发给服务器服务器说不识别这个 key它才尝试下一个。如果服务器有连接失败次数限制试两三次就被封 IP 或者要求等一会儿了。这也是为什么我反复强调IdentitiesOnly yes一定要写。第三个坑是passphrase 忘记了。私钥本身设置了 passphrase但一旦忘记没有任何找回手段只能重新生成密钥、重新上传公钥、重新配置远程仓库。相比之下公钥可以随便公开重新生成之后旧公钥作废即可。所以设置 passphrase 前建议自己评估一下安全性收益和丢失成本设置完之后可以用密码管理器存好。6. 高频命令与疑难报错排查速查环境配置讲得差不多了最后这部分是查字典环节。我按实际使用频率整理了一份命令速查表和一份报错排查清单遇到问题直接翻到这里对照。6.1 日常开发高频命令一张表操作场景命令说明克隆仓库git clone gitgithub.com:用户/仓库.gitHHTP 地址也能克隆但 SSH 更顺手查看状态git status显示工作区当前变更查看差异git diff查看未暂存的具体改动添加改动git add .暂存所有改动git add 文件名只暂存指定文件提交git commit -m 提交说明-m直接跟说明文字否则会打开编辑器推送git push首次推送指定远端分支git push -u origin main拉取git pull相当于git fetchgit merge查看历史git log --oneline --graph一行一条提交记录配合图表更直观切换分支git switch 分支名新版本推荐用switch替代checkout创建分支git switch -c 新分支名新建并切换合并分支git merge 分支名把指定分支合入当前分支暂存现场git stash存到一边回来用git stash pop回滚未提交改动git restore 文件名丢弃工作区修改谨慎操作撤销上一次提交git reset --soft HEAD~1--soft保留改动--hard会彻底丢弃这些命令没要求大家背下来但建议在理解原理的基础上多用几次。比如git add到git commit到git push这条链路其实对应的是工作区 → 暂存区 → 本地仓库 → 远程仓库四个层级的流转。概念立得住命令就不会乱。6.2 高频报错Permission deniedpublickey怎么查遇到最多的报错就是类似gitgithub.com: Permission denied (publickey). fatal: Could not read from remote repository.很多人第一反应是是不是我密码错了其实不是这个报错说明 SSH 密钥认证环节失败了。按这个顺序排查先确认 ssh-agent 里有没有加载正确的私钥。执行ssh-add -l如果有输出看是否包含你预期的那把 key 的指纹。没有的话执行ssh-add ~/.ssh/对应私钥文件。确认config文件是否匹配到了正确的 Host 和 IdentityFile。可以加-v参数看详细日志ssh -vT gitgithub.com日志里会输出尝试了哪些私钥文件。确认公钥是否确实添加到了平台。打开平台设置页和本地.pub文件逐字符核对。如果用的是公司 GitLab有时候是账号被禁用或未审核联系管理员确认。一个非常隐蔽的坑是Windows 上如果同时装了 Git for Windows 和 Windows 自带的 OpenSSHssh命令可能指向了不同的实现导致读到的~/.ssh路径不一样。Git for Windows 的 HOME 通常是C:\Users\用户名但有些工具会把 HOME 指到别处。排查方式是在 Git Bash 里执行echo $HOME看看路径是否如预期。6.3 其他三个高频坑换行、合并、分支名报错一LF will be replaced by CRLF这个告警不是错误不会阻断操作。它只是告诉你 Git 正在按照 autocrlf 规则转换换行符。如果这个提示反复出现且影响 diff 阅读回到 3.2 节把.gitattributes配置起来一劳永逸。报错二fatal: refusing to merge unrelated histories这个报错常见于两个仓库没有共同的历史基础比如你在 GitHub 上新建了一个仓库但初始化了 README本地又init了一个仓库两边历史互不相干直接pull就会报这个错。解决办法是显式允许不相关历史合并git pull origin main --allow-unrelated-histories但要注意这个操作会把两个完全不同历史合并到一起之后可能产生大量冲突建议先想清楚是不是有更合理的流程比如直接重新克隆。报错三src refspec main does not match any这个报错通常说明你还没有创建本地提交或者当前分支名不是main但推送时指定了main。解决办法是先写一个提交或者看下当前分支名再推送git branch -M main git push -u origin maingit branch -M main是把当前分支重命名为main如果你本地确实叫master也可以用这条命令统一命名。另外还有一个经常出现的提醒fatal: could not read Username for https://github.com。这个报错几乎可以断定是用 HTTPS 协议访问远程仓库时没有正确配置凭据或者凭据过期了。最简单的解决方式是把 remote 地址改成 SSH 格式参考 5.3 节。如果你确实想继续用 HTTPS可以在 Windows 凭据管理器Credential Manager里找到旧的凭据删掉下次 push 时重新输入账号密码或 Token。个人经验到最后说一句Git 和 SSH 这套东西刚开始接触会觉得概念多、命令杂、配置文件又长但真正常用的其实就那么几条命令加一个配置文件。与其把文档从头到尾背一遍不如把本文提到的配置流程完整走一遍然后找个真实的项目练手克隆、修改、提交、推送、分支合并各来一轮。踩过两三个坑之后你会发现自己对这些玄学问题基本都能独立定位了。如果后续碰到更刁钻的场景比如 Windows 上 Git 命令在 PowerShell 里的兼容问题、大规模仓库的稀疏检出sparse checkout、或者 Git LFS 大文件存储也可以顺着今天搭好的环境继续往下探索。先把地基打稳剩下的都好说。