我给大家讲个真实场景git push 的时候终端里突然冒出一长串红色报错fatal: unable to access https://github.com/xxx.git/紧接着还有一句 Could not resolve host: github.com。这时候你心里肯定咯噔一下“昨天还好好的今天怎么就连不上了”尤其是跟着教程一步步配好了 SSH 密钥却还是被 Permission denied (publickey) 反复折磨那种感觉我真的太熟了。这篇内容就是专门聊 Git 连接 GitHub 失败这件事。我会把连接链路拆开按“网络层、认证层、本地仓库层”三个维度把常见报错梳理清楚给出一套可以直接照着操作的排查顺序和解决方案。不管你是刚装好 Git 的新手还是被某个莫名报错卡住的老手这篇都能帮你省下不少排查时间。1. 连接失败问题全景梳理先搞清故障类型再谈解决方案1.1 两条连接路径决定你的排查方向完全不同Git 连 GitHub 一共就两条路HTTPS 和 SSH。用 HTTPS 方式克隆仓库地址长这样https://github.com/用户名/仓库名.git。推送代码时要求输入 GitHub 用户名和密码现在密码已经废了用的是 Personal Access Token走的是 443 端口对网络环境要求比较宽松大多数场景下都能通。用 SSH 方式克隆仓库地址长这样gitgithub.com:用户名/仓库名.git。推送代码时靠的是本机生成的公钥和私钥配对认证走的是 22 端口不需要每次输密码但前提是你的密钥成功添加到了 GitHub 账户里。你可以在任意一个仓库目录下执行git remote -v看看当前到底用的是哪条路径。如果第一行是 https:// 开头走的就是 HTTPS如果是 gitgithub.com 开头走的就是 SSH。这一步非常关键。因为很多人把 SSH 密钥配了一遍又一遍结果发现 remote 地址压根就是 HTTPS你配的密钥根本没被用到折腾半天白费力气。反过来有人一直输密码输不对其实 remote 地址走的是 SSH根本不该输密码。1.2 报错信息已经告诉了你答案别慌着删库重来Git 的报错虽然英文一大串看起来很吓人但核心信息往往就在前两行。我平时排查的习惯是先把报错分类再动手。常见的连接失败报错基本可以分成三类层级典型报错关键词问题本质网络层Could not resolve host: github.comDNS 解析失败域名没转换成 IP网络层Failed to connect to github.com port 443: Connection refused网络不通、端口被封、代理配置残留认证层Permission denied (publickey)SSH 密钥没配对或者根本没上传认证层Authentication failed for https://github.com/xxx.git/HTTPS 认证失败通常是密码/token 错误认证层Support for password authentication was removed还在用密码认证GitHub 已经不支持了本地层fatal: not a git repository当前目录根本不是 Git 仓库本地层Author identity unknown没配置 user.name 和 user.email我自己有个切身体会很多人一看到报错就跑去重新生成 SSH 密钥或者干脆把仓库删了重新 clone。这种做法不仅解决不了问题反而会让情况更乱。正确做法是先把报错读明白判断它属于哪一层然后再对症下药。2. 网络链路排查DNS 解析、hosts 残留与代理冲突2.1 DNS 解析异常GitHub 域名怎么突然“查无此人”如果你看到的报错是fatal: unable to access https://github.com/xxx.git/: Could not resolve host: github.com别急着怀疑 Git 配置先确认一下你的网络能不能把 github.com 这个域名翻译成 IP 地址。在终端里执行ping github.com如果返回“找不到主机”或者长时间超时说明 DNS 解析这一步就卡住了。再用 nslookup 看看是哪个环节出了问题nslookup github.com正常情况下会返回一个 IP 地址。如果返回不了或者返回的 IP 明显不对那基本可以确认 DNS 有问题。解决方法很简单把系统的 DNS 换成公共 DNS。国内常用的有 114.114.114.114 和 223.5.5.5这两个是国内公共 DNS速度和稳定性都不错。具体操作方式Windows 下打开“网络和 Internet 设置”-“更改适配器选项”右键正在使用的网卡选择“属性”双击“Internet 协议版本 4 (TCP/IPv4)”把首选 DNS 改成 114.114.114.114备用改成 223.5.5.5。macOS 下到“系统设置”-“网络”- 当前连接的网络 -“详细信息”-“DNS”点加号添加这两个地址。Linux 桌面版一般在网络设置里改服务器版可以改 /etc/resolv.conf。改完之后记得清一下 DNS 缓存否则旧记录还会影响判断# Windows ipconfig /flushdns # macOS sudo dscacheutil -flushcache # Linux (以 systemd 为例) sudo systemctl restart systemd-resolved我拿打电话来打个比方DNS 解析就是查电话簿github.com 是联系人姓名IP 地址是电话号码。电话簿这一页被人撕了你打多少次都是空号。换 DNS 相当于换一本靠谱的电话簿属于成本最低的修复方式。2.2 hosts 文件里的过期记录会在关键时刻“反咬一口”这个问题很容易被忽略但它真实存在。有些开发者之前为了解决 DNS 解析慢的问题曾经手动往 hosts 文件里写过 github.com 的 IP 地址。这个方法在当时也许管用但 GitHub 的 IP 不是一成不变的一旦它换了服务器你 hosts 文件里那个旧 IP 就成了“死人地址”。症状表现很典型ping 域名能通但 ssh 连不上https 也连不上甚至报错信息和正常网络问题一模一样。检查方法Windows 下打开 C:\Windows\System32\drivers\etc\hostsmacOS 和 Linux 下打开 /etc/hosts看看里面有没有类似这样的行192.30.255.112 github.com 140.82.112.4 github.com如果存在这种记录先把它们注释掉行首加 # 号或者直接删除然后执行ipconfig /flushdns让修改生效重新测试连接。这里要提醒一句GitHub 的 IP 是动态变化的手动写 hosts 并不是一劳永逸的办法。如果你之前没动过 hosts现在也不建议为图省事去网上抄一份别人的 hosts 内容因为那些 IP 很可能已经过期用了反而更糟。2.3 代理配置残留本地环境里的“隐形故障源”第三种网络层问题很隐蔽就是 Git 本身配置了代理或者终端设置了 http_proxy 环境变量但你的网络实际上根本不需要走代理。这种问题的典型报错是fatal: unable to access https://github.com/xxx.git/: Failed to connect to github.com port 443: Connection refused排查方法先看 Git 的全局代理配置git config --global --list | grep -i proxy如果有输出说明之前配过代理比如http.proxyhttp://127.0.0.1:7890 https.proxyhttp://127.0.0.1:7890如果这个代理端口现在根本没有程序在监听那 Git 每次连接都会卡在代理这一步表现为连不上。解决方法是把这俩配置清掉git config --global --unset http.proxy git config --global --unset https.proxy另外还要检查系统环境变量echo $http_proxy echo $https_proxy如果输出非空但你并不需要代理就在终端里临时清掉unset http_proxy unset https_proxy如果你是在公司网络环境工作公司确实要求走代理才能访问外网那这个代理就属于必要的上网前提。真正的问题往往出在“配过代理但后来网络环境换了代理忘了删”这种情况。我遇到过不少次在家里用 Git 突然连不上 GitHub查了半天发现是之前在公司配的代理残留没清理干净。3. SSH 连接失败密钥、认证与端口的三重门3.1 先跑一条命令定位 SSH 问题到底出在哪一环SSH 连接失败的报错通常比较统一gitgithub.com: Permission denied (publickey)。但这背后可能是多个原因好在 GitHub 提供了一个非常简单直接的测试命令ssh -T gitgithub.com这条命令本质上是在测试你的 SSH 客户端能不能和 GitHub 建立认证连接。输出的结果非常有价值如果显示Hi 用户名! Youve successfully authenticated, but GitHub does not provide shell access.说明认证成功问题出在别处比如 remote 地址写错。如果显示Permission denied (publickey)说明密钥没配对成功。如果显示Connection timed out或者Connection refused说明根本连不上 GitHub 的 22 端口可能是网络问题。如果需要更详细的日志可以加 -v 参数ssh -T -v gitgithub.com输出会比较长重点看最后几行它会告诉你 SSH 尝试了哪个用户、哪个密钥文件、是不是被拒绝了。3.2 密钥生成与添加从零到能用的完整流程如果你确认走了 SSH 方式且报错是 publickey 拒绝大概率是本机没有生成密钥或者生成的公钥没有添加到 GitHub 账户里。第一步看本机有没有密钥ls -la ~/.ssh/如果看到 id_ed25519 和 id_ed25519.pub或者 id_rsa 和 id_rsa.pub说明已经有密钥。如果没有就生成一个新的ssh-keygen -t ed25519 -C 你的邮箱提示保存位置时直接回车用默认路径提示设置 passphrase 时可以直接回车跳过相当于空密码也可以设置一个每次使用需要输入安全性更高。生成之后查看公钥内容cat ~/.ssh/id_ed25519.pub复制这一整段公钥内容然后登录 GitHub右上角头像 - Settings左侧菜单找 SSH and GPG keys点 New SSH keyTitle 填一个你认识的名字比如“我的笔记本”Key 粘贴刚才复制的内容点 Add SSH key添加完成后再次执行ssh -T gitgithub.com这次应该能看到欢迎信息了。这里面有几点特别重要只把公钥.pub 文件贴到 GitHub私钥没有 .pub 后缀的那个文件绝对不能给任何人看也不能贴到任何网站上。每台机器都要生成各自独立的密钥不需要把一台机器的密钥复制到另一台。如果你之前已经有密钥但对不上可以重新生成并添加不影响其他机器。3.3 22 端口连不上怎么办切换到 443 端口还有一种情况很棘手ssh -T gitgithub.com一直卡住或者超时但网络明明是通的。造成这种情况最常见的原因是 22 端口被网络环境限制。GitHub 官方早就考虑到了这一点专门提供了一个备用方案用 443 端口连 ssh.github.com。HTTPS 走的 443 端口在大多数网络环境下都是开放的所以这个方案的成功率很高。方法是在 ~/.ssh/config 文件不存在就新建一个中加入以下内容Host github.com HostName ssh.github.com Port 443 User git保存后再执行ssh -T gitgithub.com如果输出Hi 用户名!就说明 443 端口通道通了Git push/pull 也都会自动走这个配置不需要改 remote 地址。这个方案是 GitHub 官方提供的标准做法适合 22 端口受限的场景。我自己的经验是某些公共网络环境下 SSH 的 22 端口确实会被拦截换成 443 之后几乎没再遇到连不上的情况。3.4 ssh-agent 与免密的细节SSH 免密推送之所以能成立靠的就是 ssh-agent 这个“私钥管家”。它的作用是把你的私钥加载到内存里SSH 连接时由它替你提供密钥认证这样你就不用每次 push 都手动输入 passphrase。有几个使用细节值得注意检查 ssh-agent 是否在运行eval $(ssh-agent -s)把私钥添加进去ssh-add ~/.ssh/id_ed25519查看当前加载了哪些密钥ssh-add -lWindows 用户如果用的是系统自带的 OpenSSH一般会自动管理 ssh-agent 服务不需要额外配置。macOS 用户可以把私钥加入钥匙串避免重启后需要重新添加。另外提醒一点如果你设置了 passphrase 又重启了电脑ssh-agent 会清空内存第一次 push 时会提示你输入 passphrase。这是正常现象重新执行一次ssh-add ~/.ssh/id_ed25519即可。如果你用 Hexo 部署博客到 GitHub Pages那你在hexo d的时候走的也是这套 SSH 认证流程原理完全一样。很多人在这一步卡住多半就是上面说的密钥没添加对或者端口受限解决办法也是同一套。4. HTTPS 方式认证失败密码被弃用之后的正确打开方式4.1 GitHub 早就停用密码认证了别再输登录密码如果你用的是 HTTPS 克隆地址推送时报错信息里带有Support for password authentication was removed那恭喜你踩到了一个大坑GitHub 在 2021 年 8 月 13 日就正式停用了密码认证。也就是说你现在用 GitHub 的登录密码去 push 代码是行不通的GitHub 只接受 Personal Access Token个人访问令牌作为 HTTPS 方式的认证凭据。这个 token 本质上是一串随机字符串相当于给 Git 专用的“临时密码”。我记得刚停用密码那会儿很多人都懵了明明密码没输错为什么一直 Authentication failed其实就是因为 GitHub 不再接受密码作为 Git 操作的认证凭据了。4.2 生成 Personal Access Token五分钟搞定生成 token 的路径如下登录 GitHub - 右上角头像 - Settings左侧最下方找 Developer settings选 Personal access tokens再选 Tokens (classic)点 Generate new tokenNote 填用途说明比如“我的电脑”Expiration 选有效期可以选 30 天、90 天或者自定义勾选 repo 权限如果你需要操作私有仓库这是必须的点 Generate token生成后页面会显示一串以 ghp_ 开头的字符串这一串要立刻复制保存因为关掉页面后就再也看不到了。使用的时候就把它当成密码来用。如果当前 remote 地址是 https 方式推送时会提示输入 Username 和 PasswordUsername 填你的 GitHub 用户名Password 粘贴这串 token。如果你不想每次推送都输入可以复制 token 拼进 remote 地址里但我不推荐这么做因为 token 会明文存在 .git 目录配置里一旦别人拿到你仓库目录的访问权限token 就泄露了。4.3 清理凭据管理器里缓存过的旧密码还有一个特别隐蔽的问题凭据管理器里可能缓存了旧的账号密码或过期的 token。表现是每次 push 都提示认证失败但不管你怎么重新输入都是白搭因为 Git 优先读取缓存里的旧凭据。Windows 下打开“控制面板”-“用户账户”-“凭据管理器”-“Windows 凭据”往下翻找到 github.com 开头的条目点删除。macOS 下打开“钥匙串访问”App搜索 github把相关的条目删掉。删完后再 pushGit 会重新弹出认证窗口这时候输入新 token 就正常了。顺便检查一下 Git 的凭据助手配置git config --global credential.helper如果输出是 manager-core 或 osxkeychain说明 Git 会自动记住凭据。你也可以在 Windows 上主动配置成git config --global credential.helper manager-core这样后续 token 会被安全地存进 Windows 凭据管理器不会以明文形式躺在磁盘里。5. 本地仓库与配置脏数据看似连接问题实则是“自家后院起火”5.1 fatal: not a git repository 的真相有些报错看起来像连接问题但实际上是本地仓库的问题。经典案例就是fatal: not a git repository (or any of the parent directories): .git这句话翻译过来就是当前目录不是一个 Git 仓库。最典型的场景是你刚打开一个新文件夹还没执行git init或者你压根不在仓库目录里就直接敲了 git push、git log、git status 这些命令。解决办法分两种情况如果这个目录本来就该是仓库那就先用cd进到有 .git 目录的那个文件夹再执行 Git 命令。如果这个目录是个全新项目你打算用它来管理代码那就先执行git init初始化仓库然后配置 remote 再推送。这里要提个醒如果你原本有一个远程仓库想在本地拉取下来正确命令应该是git clone 远程地址而不是自己git init之后硬加 remote。因为 clone 会把远程仓库的完整历史和分支都拉下来init 加 remote 的方式很容易因为分支状态不一致导致 push 的时候各种冲突。5.2 用户信息没配置提交时直接报错还有一种报错是Author identity unknown Please tell me who you are.Git 提交时必须知道你是谁才能往提交记录里写作者信息。如果没有配置 user.name 和 user.email它会拒绝提交。这个报错虽然出现在 commit 阶段但很多人会误以为是连接 GitHub 失败。解决办法git config --global user.name 你的昵称 git config --global user.email 你的邮箱建议邮箱填 GitHub 登录用的那个邮箱这样你的提交记录才能正确关联到你的 GitHub 账号上那个绿色贡献图才会有记录。另外提一句很多人会问 git commit --amend 怎么用。这个命令是用来修改最近一次提交的信息的比如你刚才提交时写错了提交说明可以执行git commit --amend -m 修正后的提交说明它改动的是本地提交记录改完如果远程还没有这次提交直接 push 就行如果远程已经有历史了push 时会因为提交哈希变了而提示冲突这时候需要谨慎处理不要随便强制推送否则可能覆盖别人的提交记录。5.3 远程仓库地址写错了折腾半天都是空的如果认证和网络都正常但 push 还是失败那就得看看 remote 地址本身有没有问题。查看当前仓库的远程地址git remote -v正常输出应该有两行一行是 fetch一行是 push指向同一个地址。常见的问题有https:// 写成了 http://用户名拼写错了仓库名大小写不对GitHub 的仓库名是区分大小写的多打了个空格或者多了个斜杠修正远程地址的命令是git remote set-url origin 正确的地址改完再执行git remote -v确认然后重新 push。我处理过的不少案例里用户折腾半天网络、配了半天密钥最后发现 remote 地址里少了一个字母。所以在开始整套排查之前我强烈建议先执行git remote -v看一遍地址。这是成本最低但最容易被忽略的检查项。6. 常见错误速查表与一条完整的排查路径6.1 错误信息与解决方案速查表我把平时工作中遇到最多的错误整理成一个速查表方便你对照着快速定位报错信息问题原因直接解决方案Could not resolve host: github.comDNS 解析失败更换公共 DNS清理 DNS 缓存Failed to connect to github.com port 443: Connection refused网络不通或代理残留清理 git 代理配置检查网络连接Permission denied (publickey)SSH 密钥未配对生成密钥、上传公钥到 GitHubAuthentication failed for https://github.com/xxx.git/HTTPS 认证凭据错误改用 Personal Access TokenSupport for password authentication was removed仍在使用密码认证改用 Personal Access Tokenfatal: not a git repository当前目录不是 Git 仓库cd 到仓库目录或 git initAuthor identity unknown未配置用户信息设置 user.name 和 user.emailfatal: unable to access / SSL certificate problemSSL 证书校验失败检查系统证书配置更新 Git 版本6.2 推荐的排查顺序几分钟走完一遍如果你现在正被连接问题困扰我建议按照下面的顺序排查而不是一上来就重装 Git 或重新生成密钥。第一步看报错本身属于哪一类。是网络层、认证层还是本地层。先分类再动手。第二步确认 remote 地址。执行git remote -v确认地址对不对、走的是 SSH 还是 HTTPS。第三步测网络连通性。先ping github.com看解析是否正常再ssh -T gitgithub.com测 SSH 通道即使你用的是 HTTPS这条命令也能反映网络到 GitHub 是否通。第四步按连接方式排查认证。SSH 方式检查公钥是否在 GitHub 账户里HTTPS 方式确认 token 是否有效、凭据管理器是否缓存了旧凭据。第五步检查本地配置。git config --global --list看一下 user.name、user.email、credential.helper 和代理配置是不是正常。这一套流程走下来90% 的连接问题都能找到根因。我自己这几年处理 Git 连接问题最大的经验就是绝大多数故障不是玄学而是某个基础环节断了链子。要么是 DNS 没解析出来要么是密钥没配对要么是 token 过期了要么是本地配置冲突。别慌着重装任何东西先从最不需要动配置的地方查起一步步缩小范围问题其实很快就能浮出水面。最后分享一个小习惯每当我配置好一台新机器的 Git 环境我都会把ssh -T gitgithub.com的测试结果、remote 地址、token 生效日期这些信息记录在一个本地备忘里。下次再出问题先翻备忘很多答案都写在里面了省下的排查时间不是一星半点。
Git连接GitHub失败：从DNS到SSH密钥的完整排查指南
我给大家讲个真实场景git push 的时候终端里突然冒出一长串红色报错fatal: unable to access https://github.com/xxx.git/紧接着还有一句 Could not resolve host: github.com。这时候你心里肯定咯噔一下“昨天还好好的今天怎么就连不上了”尤其是跟着教程一步步配好了 SSH 密钥却还是被 Permission denied (publickey) 反复折磨那种感觉我真的太熟了。这篇内容就是专门聊 Git 连接 GitHub 失败这件事。我会把连接链路拆开按“网络层、认证层、本地仓库层”三个维度把常见报错梳理清楚给出一套可以直接照着操作的排查顺序和解决方案。不管你是刚装好 Git 的新手还是被某个莫名报错卡住的老手这篇都能帮你省下不少排查时间。1. 连接失败问题全景梳理先搞清故障类型再谈解决方案1.1 两条连接路径决定你的排查方向完全不同Git 连 GitHub 一共就两条路HTTPS 和 SSH。用 HTTPS 方式克隆仓库地址长这样https://github.com/用户名/仓库名.git。推送代码时要求输入 GitHub 用户名和密码现在密码已经废了用的是 Personal Access Token走的是 443 端口对网络环境要求比较宽松大多数场景下都能通。用 SSH 方式克隆仓库地址长这样gitgithub.com:用户名/仓库名.git。推送代码时靠的是本机生成的公钥和私钥配对认证走的是 22 端口不需要每次输密码但前提是你的密钥成功添加到了 GitHub 账户里。你可以在任意一个仓库目录下执行git remote -v看看当前到底用的是哪条路径。如果第一行是 https:// 开头走的就是 HTTPS如果是 gitgithub.com 开头走的就是 SSH。这一步非常关键。因为很多人把 SSH 密钥配了一遍又一遍结果发现 remote 地址压根就是 HTTPS你配的密钥根本没被用到折腾半天白费力气。反过来有人一直输密码输不对其实 remote 地址走的是 SSH根本不该输密码。1.2 报错信息已经告诉了你答案别慌着删库重来Git 的报错虽然英文一大串看起来很吓人但核心信息往往就在前两行。我平时排查的习惯是先把报错分类再动手。常见的连接失败报错基本可以分成三类层级典型报错关键词问题本质网络层Could not resolve host: github.comDNS 解析失败域名没转换成 IP网络层Failed to connect to github.com port 443: Connection refused网络不通、端口被封、代理配置残留认证层Permission denied (publickey)SSH 密钥没配对或者根本没上传认证层Authentication failed for https://github.com/xxx.git/HTTPS 认证失败通常是密码/token 错误认证层Support for password authentication was removed还在用密码认证GitHub 已经不支持了本地层fatal: not a git repository当前目录根本不是 Git 仓库本地层Author identity unknown没配置 user.name 和 user.email我自己有个切身体会很多人一看到报错就跑去重新生成 SSH 密钥或者干脆把仓库删了重新 clone。这种做法不仅解决不了问题反而会让情况更乱。正确做法是先把报错读明白判断它属于哪一层然后再对症下药。2. 网络链路排查DNS 解析、hosts 残留与代理冲突2.1 DNS 解析异常GitHub 域名怎么突然“查无此人”如果你看到的报错是fatal: unable to access https://github.com/xxx.git/: Could not resolve host: github.com别急着怀疑 Git 配置先确认一下你的网络能不能把 github.com 这个域名翻译成 IP 地址。在终端里执行ping github.com如果返回“找不到主机”或者长时间超时说明 DNS 解析这一步就卡住了。再用 nslookup 看看是哪个环节出了问题nslookup github.com正常情况下会返回一个 IP 地址。如果返回不了或者返回的 IP 明显不对那基本可以确认 DNS 有问题。解决方法很简单把系统的 DNS 换成公共 DNS。国内常用的有 114.114.114.114 和 223.5.5.5这两个是国内公共 DNS速度和稳定性都不错。具体操作方式Windows 下打开“网络和 Internet 设置”-“更改适配器选项”右键正在使用的网卡选择“属性”双击“Internet 协议版本 4 (TCP/IPv4)”把首选 DNS 改成 114.114.114.114备用改成 223.5.5.5。macOS 下到“系统设置”-“网络”- 当前连接的网络 -“详细信息”-“DNS”点加号添加这两个地址。Linux 桌面版一般在网络设置里改服务器版可以改 /etc/resolv.conf。改完之后记得清一下 DNS 缓存否则旧记录还会影响判断# Windows ipconfig /flushdns # macOS sudo dscacheutil -flushcache # Linux (以 systemd 为例) sudo systemctl restart systemd-resolved我拿打电话来打个比方DNS 解析就是查电话簿github.com 是联系人姓名IP 地址是电话号码。电话簿这一页被人撕了你打多少次都是空号。换 DNS 相当于换一本靠谱的电话簿属于成本最低的修复方式。2.2 hosts 文件里的过期记录会在关键时刻“反咬一口”这个问题很容易被忽略但它真实存在。有些开发者之前为了解决 DNS 解析慢的问题曾经手动往 hosts 文件里写过 github.com 的 IP 地址。这个方法在当时也许管用但 GitHub 的 IP 不是一成不变的一旦它换了服务器你 hosts 文件里那个旧 IP 就成了“死人地址”。症状表现很典型ping 域名能通但 ssh 连不上https 也连不上甚至报错信息和正常网络问题一模一样。检查方法Windows 下打开 C:\Windows\System32\drivers\etc\hostsmacOS 和 Linux 下打开 /etc/hosts看看里面有没有类似这样的行192.30.255.112 github.com 140.82.112.4 github.com如果存在这种记录先把它们注释掉行首加 # 号或者直接删除然后执行ipconfig /flushdns让修改生效重新测试连接。这里要提醒一句GitHub 的 IP 是动态变化的手动写 hosts 并不是一劳永逸的办法。如果你之前没动过 hosts现在也不建议为图省事去网上抄一份别人的 hosts 内容因为那些 IP 很可能已经过期用了反而更糟。2.3 代理配置残留本地环境里的“隐形故障源”第三种网络层问题很隐蔽就是 Git 本身配置了代理或者终端设置了 http_proxy 环境变量但你的网络实际上根本不需要走代理。这种问题的典型报错是fatal: unable to access https://github.com/xxx.git/: Failed to connect to github.com port 443: Connection refused排查方法先看 Git 的全局代理配置git config --global --list | grep -i proxy如果有输出说明之前配过代理比如http.proxyhttp://127.0.0.1:7890 https.proxyhttp://127.0.0.1:7890如果这个代理端口现在根本没有程序在监听那 Git 每次连接都会卡在代理这一步表现为连不上。解决方法是把这俩配置清掉git config --global --unset http.proxy git config --global --unset https.proxy另外还要检查系统环境变量echo $http_proxy echo $https_proxy如果输出非空但你并不需要代理就在终端里临时清掉unset http_proxy unset https_proxy如果你是在公司网络环境工作公司确实要求走代理才能访问外网那这个代理就属于必要的上网前提。真正的问题往往出在“配过代理但后来网络环境换了代理忘了删”这种情况。我遇到过不少次在家里用 Git 突然连不上 GitHub查了半天发现是之前在公司配的代理残留没清理干净。3. SSH 连接失败密钥、认证与端口的三重门3.1 先跑一条命令定位 SSH 问题到底出在哪一环SSH 连接失败的报错通常比较统一gitgithub.com: Permission denied (publickey)。但这背后可能是多个原因好在 GitHub 提供了一个非常简单直接的测试命令ssh -T gitgithub.com这条命令本质上是在测试你的 SSH 客户端能不能和 GitHub 建立认证连接。输出的结果非常有价值如果显示Hi 用户名! Youve successfully authenticated, but GitHub does not provide shell access.说明认证成功问题出在别处比如 remote 地址写错。如果显示Permission denied (publickey)说明密钥没配对成功。如果显示Connection timed out或者Connection refused说明根本连不上 GitHub 的 22 端口可能是网络问题。如果需要更详细的日志可以加 -v 参数ssh -T -v gitgithub.com输出会比较长重点看最后几行它会告诉你 SSH 尝试了哪个用户、哪个密钥文件、是不是被拒绝了。3.2 密钥生成与添加从零到能用的完整流程如果你确认走了 SSH 方式且报错是 publickey 拒绝大概率是本机没有生成密钥或者生成的公钥没有添加到 GitHub 账户里。第一步看本机有没有密钥ls -la ~/.ssh/如果看到 id_ed25519 和 id_ed25519.pub或者 id_rsa 和 id_rsa.pub说明已经有密钥。如果没有就生成一个新的ssh-keygen -t ed25519 -C 你的邮箱提示保存位置时直接回车用默认路径提示设置 passphrase 时可以直接回车跳过相当于空密码也可以设置一个每次使用需要输入安全性更高。生成之后查看公钥内容cat ~/.ssh/id_ed25519.pub复制这一整段公钥内容然后登录 GitHub右上角头像 - Settings左侧菜单找 SSH and GPG keys点 New SSH keyTitle 填一个你认识的名字比如“我的笔记本”Key 粘贴刚才复制的内容点 Add SSH key添加完成后再次执行ssh -T gitgithub.com这次应该能看到欢迎信息了。这里面有几点特别重要只把公钥.pub 文件贴到 GitHub私钥没有 .pub 后缀的那个文件绝对不能给任何人看也不能贴到任何网站上。每台机器都要生成各自独立的密钥不需要把一台机器的密钥复制到另一台。如果你之前已经有密钥但对不上可以重新生成并添加不影响其他机器。3.3 22 端口连不上怎么办切换到 443 端口还有一种情况很棘手ssh -T gitgithub.com一直卡住或者超时但网络明明是通的。造成这种情况最常见的原因是 22 端口被网络环境限制。GitHub 官方早就考虑到了这一点专门提供了一个备用方案用 443 端口连 ssh.github.com。HTTPS 走的 443 端口在大多数网络环境下都是开放的所以这个方案的成功率很高。方法是在 ~/.ssh/config 文件不存在就新建一个中加入以下内容Host github.com HostName ssh.github.com Port 443 User git保存后再执行ssh -T gitgithub.com如果输出Hi 用户名!就说明 443 端口通道通了Git push/pull 也都会自动走这个配置不需要改 remote 地址。这个方案是 GitHub 官方提供的标准做法适合 22 端口受限的场景。我自己的经验是某些公共网络环境下 SSH 的 22 端口确实会被拦截换成 443 之后几乎没再遇到连不上的情况。3.4 ssh-agent 与免密的细节SSH 免密推送之所以能成立靠的就是 ssh-agent 这个“私钥管家”。它的作用是把你的私钥加载到内存里SSH 连接时由它替你提供密钥认证这样你就不用每次 push 都手动输入 passphrase。有几个使用细节值得注意检查 ssh-agent 是否在运行eval $(ssh-agent -s)把私钥添加进去ssh-add ~/.ssh/id_ed25519查看当前加载了哪些密钥ssh-add -lWindows 用户如果用的是系统自带的 OpenSSH一般会自动管理 ssh-agent 服务不需要额外配置。macOS 用户可以把私钥加入钥匙串避免重启后需要重新添加。另外提醒一点如果你设置了 passphrase 又重启了电脑ssh-agent 会清空内存第一次 push 时会提示你输入 passphrase。这是正常现象重新执行一次ssh-add ~/.ssh/id_ed25519即可。如果你用 Hexo 部署博客到 GitHub Pages那你在hexo d的时候走的也是这套 SSH 认证流程原理完全一样。很多人在这一步卡住多半就是上面说的密钥没添加对或者端口受限解决办法也是同一套。4. HTTPS 方式认证失败密码被弃用之后的正确打开方式4.1 GitHub 早就停用密码认证了别再输登录密码如果你用的是 HTTPS 克隆地址推送时报错信息里带有Support for password authentication was removed那恭喜你踩到了一个大坑GitHub 在 2021 年 8 月 13 日就正式停用了密码认证。也就是说你现在用 GitHub 的登录密码去 push 代码是行不通的GitHub 只接受 Personal Access Token个人访问令牌作为 HTTPS 方式的认证凭据。这个 token 本质上是一串随机字符串相当于给 Git 专用的“临时密码”。我记得刚停用密码那会儿很多人都懵了明明密码没输错为什么一直 Authentication failed其实就是因为 GitHub 不再接受密码作为 Git 操作的认证凭据了。4.2 生成 Personal Access Token五分钟搞定生成 token 的路径如下登录 GitHub - 右上角头像 - Settings左侧最下方找 Developer settings选 Personal access tokens再选 Tokens (classic)点 Generate new tokenNote 填用途说明比如“我的电脑”Expiration 选有效期可以选 30 天、90 天或者自定义勾选 repo 权限如果你需要操作私有仓库这是必须的点 Generate token生成后页面会显示一串以 ghp_ 开头的字符串这一串要立刻复制保存因为关掉页面后就再也看不到了。使用的时候就把它当成密码来用。如果当前 remote 地址是 https 方式推送时会提示输入 Username 和 PasswordUsername 填你的 GitHub 用户名Password 粘贴这串 token。如果你不想每次推送都输入可以复制 token 拼进 remote 地址里但我不推荐这么做因为 token 会明文存在 .git 目录配置里一旦别人拿到你仓库目录的访问权限token 就泄露了。4.3 清理凭据管理器里缓存过的旧密码还有一个特别隐蔽的问题凭据管理器里可能缓存了旧的账号密码或过期的 token。表现是每次 push 都提示认证失败但不管你怎么重新输入都是白搭因为 Git 优先读取缓存里的旧凭据。Windows 下打开“控制面板”-“用户账户”-“凭据管理器”-“Windows 凭据”往下翻找到 github.com 开头的条目点删除。macOS 下打开“钥匙串访问”App搜索 github把相关的条目删掉。删完后再 pushGit 会重新弹出认证窗口这时候输入新 token 就正常了。顺便检查一下 Git 的凭据助手配置git config --global credential.helper如果输出是 manager-core 或 osxkeychain说明 Git 会自动记住凭据。你也可以在 Windows 上主动配置成git config --global credential.helper manager-core这样后续 token 会被安全地存进 Windows 凭据管理器不会以明文形式躺在磁盘里。5. 本地仓库与配置脏数据看似连接问题实则是“自家后院起火”5.1 fatal: not a git repository 的真相有些报错看起来像连接问题但实际上是本地仓库的问题。经典案例就是fatal: not a git repository (or any of the parent directories): .git这句话翻译过来就是当前目录不是一个 Git 仓库。最典型的场景是你刚打开一个新文件夹还没执行git init或者你压根不在仓库目录里就直接敲了 git push、git log、git status 这些命令。解决办法分两种情况如果这个目录本来就该是仓库那就先用cd进到有 .git 目录的那个文件夹再执行 Git 命令。如果这个目录是个全新项目你打算用它来管理代码那就先执行git init初始化仓库然后配置 remote 再推送。这里要提个醒如果你原本有一个远程仓库想在本地拉取下来正确命令应该是git clone 远程地址而不是自己git init之后硬加 remote。因为 clone 会把远程仓库的完整历史和分支都拉下来init 加 remote 的方式很容易因为分支状态不一致导致 push 的时候各种冲突。5.2 用户信息没配置提交时直接报错还有一种报错是Author identity unknown Please tell me who you are.Git 提交时必须知道你是谁才能往提交记录里写作者信息。如果没有配置 user.name 和 user.email它会拒绝提交。这个报错虽然出现在 commit 阶段但很多人会误以为是连接 GitHub 失败。解决办法git config --global user.name 你的昵称 git config --global user.email 你的邮箱建议邮箱填 GitHub 登录用的那个邮箱这样你的提交记录才能正确关联到你的 GitHub 账号上那个绿色贡献图才会有记录。另外提一句很多人会问 git commit --amend 怎么用。这个命令是用来修改最近一次提交的信息的比如你刚才提交时写错了提交说明可以执行git commit --amend -m 修正后的提交说明它改动的是本地提交记录改完如果远程还没有这次提交直接 push 就行如果远程已经有历史了push 时会因为提交哈希变了而提示冲突这时候需要谨慎处理不要随便强制推送否则可能覆盖别人的提交记录。5.3 远程仓库地址写错了折腾半天都是空的如果认证和网络都正常但 push 还是失败那就得看看 remote 地址本身有没有问题。查看当前仓库的远程地址git remote -v正常输出应该有两行一行是 fetch一行是 push指向同一个地址。常见的问题有https:// 写成了 http://用户名拼写错了仓库名大小写不对GitHub 的仓库名是区分大小写的多打了个空格或者多了个斜杠修正远程地址的命令是git remote set-url origin 正确的地址改完再执行git remote -v确认然后重新 push。我处理过的不少案例里用户折腾半天网络、配了半天密钥最后发现 remote 地址里少了一个字母。所以在开始整套排查之前我强烈建议先执行git remote -v看一遍地址。这是成本最低但最容易被忽略的检查项。6. 常见错误速查表与一条完整的排查路径6.1 错误信息与解决方案速查表我把平时工作中遇到最多的错误整理成一个速查表方便你对照着快速定位报错信息问题原因直接解决方案Could not resolve host: github.comDNS 解析失败更换公共 DNS清理 DNS 缓存Failed to connect to github.com port 443: Connection refused网络不通或代理残留清理 git 代理配置检查网络连接Permission denied (publickey)SSH 密钥未配对生成密钥、上传公钥到 GitHubAuthentication failed for https://github.com/xxx.git/HTTPS 认证凭据错误改用 Personal Access TokenSupport for password authentication was removed仍在使用密码认证改用 Personal Access Tokenfatal: not a git repository当前目录不是 Git 仓库cd 到仓库目录或 git initAuthor identity unknown未配置用户信息设置 user.name 和 user.emailfatal: unable to access / SSL certificate problemSSL 证书校验失败检查系统证书配置更新 Git 版本6.2 推荐的排查顺序几分钟走完一遍如果你现在正被连接问题困扰我建议按照下面的顺序排查而不是一上来就重装 Git 或重新生成密钥。第一步看报错本身属于哪一类。是网络层、认证层还是本地层。先分类再动手。第二步确认 remote 地址。执行git remote -v确认地址对不对、走的是 SSH 还是 HTTPS。第三步测网络连通性。先ping github.com看解析是否正常再ssh -T gitgithub.com测 SSH 通道即使你用的是 HTTPS这条命令也能反映网络到 GitHub 是否通。第四步按连接方式排查认证。SSH 方式检查公钥是否在 GitHub 账户里HTTPS 方式确认 token 是否有效、凭据管理器是否缓存了旧凭据。第五步检查本地配置。git config --global --list看一下 user.name、user.email、credential.helper 和代理配置是不是正常。这一套流程走下来90% 的连接问题都能找到根因。我自己这几年处理 Git 连接问题最大的经验就是绝大多数故障不是玄学而是某个基础环节断了链子。要么是 DNS 没解析出来要么是密钥没配对要么是 token 过期了要么是本地配置冲突。别慌着重装任何东西先从最不需要动配置的地方查起一步步缩小范围问题其实很快就能浮出水面。最后分享一个小习惯每当我配置好一台新机器的 Git 环境我都会把ssh -T gitgithub.com的测试结果、remote 地址、token 生效日期这些信息记录在一个本地备忘里。下次再出问题先翻备忘很多答案都写在里面了省下的排查时间不是一星半点。
