Git提交推送报网络连接失败？一套完整排查流程帮你定位根因

git提交、拉取、推送代码时提示网络连接失败这个问题我在实际项目里遇到过不下十次。印象最深的一次是上午还能正常 git pull下午执行 git push 就直接报 fatal: unable to access试了重启电脑、切换网络、重装 Git 都没有用最后发现是全局配置里残留了一行指向内网地址的转发设置。类似的情况还有 DNS 解析失败、SSL 证书不信任、SSH 密钥不匹配等等表象都是“网络连接失败”根因却五花八门。这篇内容我就把 Git 提交、拉取、推送时报网络连接失败这一类问题的完整排查过程写出来。不管你是刚学 Git 的新手还是已经在用 Git 的老手按这个顺序过一遍大部分问题都能快速定位到根因。1. 先看现象git突然连不上仓库报错长什么样很多人一看到“网络连接失败”就开始反复重试这是最浪费时间的事情。Git 的报错信息虽然看起来乱但其实是有层次的。先把报错完整复制下来不要只看最后一行通常第一行和最后一行会给你最重要的线索。1.1 最常见的几类报错文本HTTPS 协议下最常见的报错长这样fatal: unable to access https://gitee.com/xxx/project.git/: Could not resolve host: gitee.com这句话的意思是 Git 通过 HTTPS 访问远程仓库时第一步域名解析就失败了。域名解析不到自然连不上服务器。还有一种很常见fatal: unable to access https://gitlab.example.com/team/project.git/: Failed to connect to gitlab.example.com port 443: Connection timed out这说明域名能解析但 TCP 端口 443 连不通要么被防火墙拦了要么网络不通。SSH 协议下常见的报错是ssh: connect to host gitlab.example.com port 22: Connection timed out fatal: Could not read from remote repository.它提示 SSH 客户端连不上服务器的 22 端口。这里要特别注意即使你看到“fatal”这种词它也不一定代表 Git 本身出问题了更像是底层网络通道断了。推送大文件时还会出现RPC failed; HTTP 500 curl 22 The requested URL returned error: 500或者error: RPC failed; curl 18 HTTP/2 stream 0 was not closed cleanly这类报错通常跟网络质量、缓冲区、仓库平台限制有关不是简单的“连不上”。1.2 为什么这些报错都指向“网络连接失败”Git 本身不是一个独立的网络协议工具它底层依赖 libcurl 或者 SSH 客户端来和远程服务器通信。一次普通的 git push大致会经历这几个阶段解析远程仓库地址里的主机名依赖 DNS与服务器建立 TCP 连接HTTPS 默认 443 端口SSH 默认 22 端口HTTPS 需要完成 TLS 握手确认证书可信身份认证HTTPS 用账号密码或访问令牌SSH 用公钥私钥协商传输内容把本地提交对象上传到服务器从上面这个链路就能看出来任何一个环节出问题Git 最后给你呈现出来的可能都是“网络连接失败”。这就像寄快递地址写错了快递员找不到地方收件人地址楼栋封锁了快递员进不去小区门卫不让代收都会导致包裹送不到但你收到的通知可能都只是一句“派送失败”。所以遇到 Git 网络报错先别急着反复试按阶段排查才是最高效的。2. 排查思路不要把时间浪费在重复试我的习惯是先花两分钟把“通道类型”和“配置现状”摸清楚再决定接下来往哪个方向查。这样做的好处是你不会在 DNS、证书、密钥三个完全不同的方向之间来回折腾。2.1 先分清是HTTPS还是SSH通道执行git remote -v这个命令会显示你当前仓库配置的远程地址。如果地址以https://开头走的就是 HTTPS 通道如果以git开头比如gitgitee.com:xxx/project.git走的就是 SSH 通道。两条通道的排查侧重点完全不同HTTPS 通道重点查 DNS、443 端口、证书、账号凭据、Git 的 HTTP 传输配置SSH 通道重点查 22 端口、SSH 密钥是否匹配、known_hosts 记录、ssh config 配置很多人从头到尾都不知道自己用的是哪种方式报错了只能瞎猜。先跑一遍git remote -v大概能排除一半问题。2.2 用最小命令定位网络问题在排查 Git 本身之前我建议先用最基础的网络命令把“本机到远程服务器”这一段连通性测清楚。这一组命令就是我的“最小诊断集”nslookup gitee.com curl -vI https://gitee.com第一条命令看域名能不能解析出 IP第二条命令看 HTTPS 能不能正常完成连接并取得响应头。如果curl能正常返回 HTTP 状态码说明 DNS、TCP、TLS 这一整条链路都没问题。这时候 Git 还是报错那问题大概率出在 Git 自己的配置、账号凭据或者传输参数上。如果curl也失败了那就能顺着 curl 的报错去判断到底是哪一层出了问题是 DNS 解析失败还是 TCP 连接被拒还是证书校验不过。这里要特别提醒一个误区不要只靠ping去判断网络通不通。很多服务器会屏蔽 ICMP 协议导致 ping 不通但实际 443 端口是通的反过来ping 通了也可能 443 端口进不去。所以要看 TCP 端口而不是只看 ping 的结果。2.3 检查本地git配置里的坑Git 的配置分为三层系统级、全局级、仓库级。一般优先查全局配置git config --global --list输出里可能出现很多项目重点关注的是以http.、https.、remote.开头的配置。有一个很典型的情况某些开发工具或者网络工具在安装时会在全局配置文件里写入一个指向本机或者内网地址的转发设置。只要这个设置指向的地址不可达你所有的 git push、git pull、git fetch 都会报网络连接失败。如果你看到git config --global --list的输出里有以http.开头的配置项值是一个形如http://127.0.0.1:8080或者http://192.168.x.x:8080的地址那么基本可以断定请求被引导到了一个不该去的中转节点。清理方法后面我会专门讲这里你先记住一个原则Git 报网络连接失败先看自己的配置再怀疑外部网络。3. 常见原因逐个拆解为了让你排查的时候心里有数我把实际工作中最常见的几类原因拆开来讲。每一类我都会给出对应的现象特征、为什么会出现、以及处理方向。3.1 环境变量与全局配置里的转发设置残留这类问题特别隐蔽因为它不是 Git 本身配置错了而是整个操作系统的环境变量里残留了转发设置Git 只是“忠实”地读取了它。很多开发者可能在电脑上装过网络调试工具、抓包工具、内网加速软件甚至某些公司统一安装的安全组件。这些工具安装时会在系统环境变量里写入 HTTP 相关的全局变量值一般是一个地址。只要这些变量存在Git 的 HTTP 请求就会先尝试把这个地址当成中间服务器连接不上就报错。怎么检查在 Windows 上打开 PowerShell执行Get-ChildItem Env:在 Linux 或 macOS 上执行env然后人工浏览输出重点看有没有以http_、https_、all_开头的环境变量而且值是一个以http://开头的地址。如果你并不在公司内网也不需要通过特定服务器上网那么这类变量基本就是元凶。另外Git 自己的全局配置也可能有类似问题。执行git config --global --edit这会打开你的全局配置文件。如果你看到[http]段或者[https]段里写着某个内网地址或本机地址那就删掉对应行。要特别注意的是**不要整段全删也不要删掉你公司要求设置的配置。**如果你本来就在公司内网公司强制要求设置转发参数才能访问内部 GitLab那这时候要做的反而是确保它存在且正确而不是删除。3.2 DNS解析失败DNS 解析失败的特征非常明显报错里一定会有这句话Could not resolve host: xxx.com这种情况的意思是你的电脑能发出网络请求但系统不知道gitee.com这个域名对应哪个 IP。我遇到过的情况大致分三种第一种公司内网环境。你从公司 WiFi 切到了家里网络或者从家里网络切到了公司网络但 DNS 服务器没有同步切换。公司内网要求使用内部 DNS 才能解析内部的 GitLab 域名一旦 DNS 不对内网域名就解析不到。第二种hosts 文件被改动过。有人为了提高某些域名的解析速度在 hosts 文件里写死了域名和 IP 的映射。但后来 IP 变了hosts 文件里的还是老的导致 Git 连不上。Windows 的 hosts 文件在C:\Windows\System32\drivers\etc\hostsLinux 和 macOS 在/etc/hosts检查一下有没有相关域名的老映射。第三种DNS 缓存污染或者缓存错误。这种情况刷新 DNS 缓存通常能解决。各系统刷新 DNS 缓存的命令# Windows ipconfig /flushdns # macOS sudo dscacheutil -flushcache sudo killall -HUP mDNSResponder # Linux使用 systemd 的系统 sudo resolvectl flush-caches如果你想快速验证是公共 DNS 能不能解析可以用nslookup gitee.com 223.5.5.5如果指定 223.5.5.5 能解析出 IP说明问题出在本地 DNS 设置上可以先把网卡 DNS 改成 223.5.5.5 再测试。3.3 防火墙、安全软件和端口不通如果报错是Failed to connect to xxx port 443: Connection timed out或者ssh: connect to host xxx port 22: Connection timed out那基本可以确定是“TCP 层不通”。有可能是本机防火墙拦截了出口也可能是公司出口防火墙做了限制还有可能是远程服务器防火墙拒绝了你的 IP。这类问题的排查思路很简单就是直接测端口。Windows 上用 PowerShell 执行Test-NetConnection gitee.com -Port 443Linux 或 macOS 上可以用nc -vz gitee.com 443如果端口测试失败你就要考虑本地防火墙是否放行了 Git 相关程序安全软件、杀毒软件是否拦截了 Git 进程公司网络是否只允许特定端口远程仓库服务器是否调整了端口这里有一个实用的替代方案如果 SSH 的 22 端口不通但 HTTPS 的 443 端口是通的那可以把远程地址从 SSH 协议改成 HTTPS 协议。反过来也一样。协议切换能绕过不少端口限制。3.4 SSL证书与CA校验问题这类问题在自建 GitLab 的场景里特别常见。报错信息一般长这样SSL certificate problem: unable to get local issuer certificate或者server certificate verification failed还有可能是gnutls_handshake() failed出现这些报错说明 TCP 连接是通的但 TLS 握手阶段Git 发现服务器返回的证书不能被本地信任。原因往往是公司 GitLab 使用自签证书本机没有安装对应的根证书公司内网用 HTTPS 中间设备对流量做了证书替换本机不信任那个证书系统时间不对导致证书有效期判断失败先执行date看系统时间是不是正确。时间不准的话先把时间校准了再试。如果确实是自签证书问题解决办法是把公司 GitLab 的 CA 证书安装到系统信任区Windows 上双击证书文件选择安装到“受信任的根证书颁发机构”macOS 上用“钥匙串访问”导入证书并设置为始终信任Linux 上把证书复制到/usr/local/share/ca-certificates/然后执行sudo update-ca-certificates另外还可以给 Git 单独指定 CA 证书git config --global http.sslCAInfo /path/to/your-ca.crt这个方式特别适合公司内网环境不用动系统证书只让 Git 信任这个证书。需要强调一点网上很多人建议直接关闭 SSL 校验比如执行git -c http.sslVerifyfalse pull或者设置git config --global http.sslVerify false不到万不得已不要这么做。关闭证书校验等于让你的 Git 传输暴露在中间人攻击的风险里。如果只是临时排查可以试一次确认是不是证书问题但确认之后一定要把校验重新打开或者正确安装 CA 证书。3.5 SSH密钥不匹配或未添加如果你的远程地址是git开头的 SSH 地址报错却是Permission denied (publickey) fatal: Could not read from remote repository.那么网络本身通常是通的问题出在“身份认证”环节。SSH 的认证机制是你本地保存私钥远程平台保存你的公钥。推送代码时远程平台会用公钥验证你的私钥签名。如果本地私钥不存在、被改了名字、或者对应的公钥没有添加到平台就会出现上面的报错。排查步骤很简单。先看本地有没有密钥ls -la ~/.ssh常见的私钥文件名是id_ed25519、id_rsa。对应的公钥是带.pub后缀的文件。如果没有密钥生成一个新的ssh-keygen -t ed25519 -C 你的备注信息一路回车生成完会得到一个公钥文件比如~/.ssh/id_ed25519.pub。用文本编辑器打开这个.pub文件把内容完整复制然后到代码托管平台的“SSH Keys”设置页面粘贴保存。验证是否成功ssh -T gitgitee.com如果返回类似Hi yourname! Youve successfully authenticated, but GIT does not provide shell access.说明 SSH 认证已经通了。如果你有多个代码托管平台账号比如公司 GitLab 和个人的 Gitee那还需要检查~/.ssh/config文件。这个文件可以针对不同的 Host 指定不同的私钥。配置写错了Git 可能加载了错误的私钥也会导致认证失败。排查时执行ssh -vT gitgitee.com看输出里加载的是哪个私钥文件和你在平台上添加的公钥是否对应。如果对应不上就去改 config 文件。3.6 大文件、超时和传输失败有时候网络本身是通的认证也通过了但推送时还是报错RPC failed; curl 18 HTTP/2 stream 0 was not closed cleanlyThe requested URL returned error: 413Connection reset by peer这些报错往往发生在推送大文件、或者仓库历史特别大的时候。原因通常是提交里包含了超过平台限制的大文件比如超过 100MB 的设计稿、视频、压缩包单次 HTTP 请求体过大超过了 Git 默认缓冲区限制网络带宽不够稳定长时间传输被打断遇到这种问题第一步先检查是不是把大文件提交进去了git log --oneline --stat -n 5如果最近一次提交里有一个很大的文件立刻从提交中拆出来。如果还没推上去可以撤销最近一次提交但保留工作区改动git reset --soft HEAD~1然后重新整理提交把大文件排除在外。已经不在提交里的大文件可以后面用 Git LFS 管理。如果文件不算特别大只是传输经常中断可以调大 Git 的 HTTP 缓冲区和超时参数git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 1000 git config --global http.lowSpeedTime 30http.postBuffer设置的是单次 HTTP 请求允许发送的最大字节数这里调到了 500MB 左右。遇到稍大的提交这个参数能减少“分段传输被服务器断开”的概率。http.lowSpeedLimit和http.lowSpeedTime的意思是如果传输速度低于 1000 字节每秒持续 30 秒Git 就主动断开。这个配置能避免 Git 一直卡在那里让你更快知道问题。如果是经常需要管理二进制大文件的仓库建议直接用 Git LFS。初始化一下git lfs install git lfs track *.zip git add .gitattributes git commit -m track zip files with LFS之后这些被 LFS 跟踪的文件会走独立的存储通道不会把 Git 仓库本身撑爆推送的稳定性会高很多。4. 实操一步步把git恢复到能正常推送拉取前面讲了原理和原因这节我带你完整走一遍实操。以一个真实的排查过程为例子我在某个项目里执行 git push 报错内容是fatal: unable to access https://gitee.com/xxx/project.git/: Failed to connect to gitee.com port 443: Connection timed out。下面是我一步步处理的过程。4.1 第一步核对远程地址和协议我先执行git remote -v输出origin https://gitee.com/xxx/project.git (fetch) origin https://gitee.com/xxx/project.git (push)地址没问题确实走的是 HTTPS。这一步主要是排除“远程地址拼错”或者“仓库迁移后地址没更新”的情况。比如同事把仓库从旧域名迁到了新域名你本地还指向旧地址Git 连不上是必然的。如果发现地址不对用git remote set-url origin https://gitee.com/新地址/project.git更新即可。4.2 第二步检查并清理转发配置远程地址没问题接着查 Git 配置git config --global --list我在输出里看到了一个可疑的http.开头的配置项值指向一个192.168.x.x的内网地址。当时我人并不在公司内网这个配置就是历史遗留问题。Git 每次访问远程仓库时都会先把请求转发到那个内网地址自然连不上。清理方法是编辑全局配置文件git config --global --edit这会用默认文本编辑器打开~/.gitconfig我找到[http]段把里面指向内网地址的那一行删掉保存退出。然后重新执行git pull这一次就正常了。这里想多提醒一句如果你是在公司环境里这种配置有可能是公司 IT 要求设置的千万别照搬“删除”这个操作。判断标准很简单离开公司内网这个配置导致连不上那它在当前网络环境里就是有害的回到公司内网如果不配置就连不上它就是必需的。不同环境要学会区分。4.3 第三步DNS与IP连通性验证如果清理完配置还不行我就做网络层验证nslookup gitee.com看看域名能不能解析出 IP。如果提示server cant find说明 DNS 有问题按前面说的方式刷新 DNS 缓存或者换 DNS 服务器。接着测 HTTPS 连通性curl -vI https://gitee.com如果 curl 正常返回说明从本机到 gitee.com 的网络链路是通的问题一定出在 Git 的传输配置或认证上。如果 curl 也报错则看报错具体卡在哪一步。是 DNS、TCP、还是 TLS。有时还需要看端口通不通# Windows Test-NetConnection gitee.com -Port 443 # Linux / macOS nc -vz gitee.com 443端口不通就回到防火墙和网络策略的问题上。4.4 第四步SSH连接验证与密钥重建如果我的远程地址是 SSH 协议那我会跳过 HTTPS 的 curl 测试直接执行ssh -vT gitgitee.com这个命令会把 SSH 握手过程完整打印出来非常直观。如果卡在connect to host这种地方说明端口不通如果出现Permission denied说明密钥没有被接受。如果是密钥问题就先看本地有没有密钥ls -la ~/.ssh没有密钥就重新生成ssh-keygen -t ed25519 -C your_emailexample.com然后把~/.ssh/id_ed25519.pub的内容复制到平台。再回来执行ssh -T gitgitee.com能收到欢迎信息就说明通了。这里有一个小的经验如果你之前一直用 SSH 好好的突然某一天报Permission denied而且你没改过任何东西那很可能是平台的公钥被清理了或者是系统升级后 known_hosts 里的主机密钥和服务器不匹配。可以用这个命令清除旧记录ssh-keygen -R gitee.com然后再重新连接一次。4.5 第五步SSL异常的处理在 HTTPS 通道下如果报错是证书相关我先执行curl -vI https://gitlab.example.com观察输出里有没有类似SSL certificate problem的提示。公司自建 GitLab 如果用了自签证书我会把证书下载下来然后给 Git 配置指定 CAgit config --global http.sslCAInfo /etc/ssl/certs/gitlab-ca.crt配置完后重新拉取证书校验就能通过。如果还不知道为什么系统时间会导致证书错误这里再说一次先检查本机时间很多莫名其妙的 TLS 报错把时间校准就好了。4.6 第六步调整HTTP传输参数解决超时如果网络链路都正常但推送大仓库时仍然超时或者中断我就会调整 Git 的 HTTP 传输参数。我当时遇到的情况是仓库里有一个将近 200MB 的 SQL 备份文件被误提交推送时反复出现RPC failed; HTTP 500 curl 22。处理步骤是先取消最近一次提交保留工作区修改git reset --soft HEAD~1把大文件从暂存区移除git rm --cached huge_file.sql重新提交一次继续推送git commit -m remove huge file from commit git push如果你确认文件是必须提交的而且平台也支持大文件那用 Git LFSgit lfs install git lfs track *.sql git add .gitattributes git commit -m track sql files with LFS git push在调整参数方面为了保证传输稳定性我会用git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 1000 git config --global http.lowSpeedTime 30这些参数不是越大越好但针对常见的中断场景能明显降低失败概率。5. 问题排查速查表下面这张表是我自己总结的遇到问题直接对着查能省很多时间。报错关键词常见原因优先检查点参考处理Could not resolve hostDNS 解析失败nslookup检查 hosts 文件换 DNS、刷新缓存、清理 hostsConnection timed out网络不通、防火墙拦截、路由问题测试 443/22 端口切换网络、检查防火墙、换协议Connection refused端口不对、服务未启动、本地转发配置残留确认远程 URL 和端口更正 URL、清理本地转发配置SSL certificate problem / TLS handshake failure证书链不受信任、系统时间不对datecurl -v安装 CA 证书、指定 sslCAInfoPermission denied (publickey)SSH 公钥未添加、私钥不匹配ssh -T git...查看加载的私钥重建密钥、添加公钥到平台RPC failed / HTTP 413 / HTTP 500大文件、缓冲区不足、网关限制查看最近提交里的大文件拆分提交、调整 postBuffer、用 LFSearly EOF / index-pack failed传输中断、仓库太大、网络抖动网络稳定性、仓库大小用 SSH、调整传输参数、浅克隆unable to get local issuer certificate根证书缺失检查系统信任库安装根证书、指定 CA 路径这张表不是万能的但覆盖了我在实际工作中遇到的绝大多数“网络连接失败”场景。6. 写在最后的几点经验这套问题我踩过很多次坑最后总结几个自己的习惯希望能帮你少走弯路。第一个习惯是遇到 Git 网络报错永远先跑三连命令。git remote -v git config --global --list curl -vI 你的远程仓库地址这三条命令跑完大概能判断出问题是出在地址、配置还是网络。我见过太多人一上来就重装 Git、重启电脑结果发现只是全局配置里一行地址的问题。第二个习惯是IDE 里报错立刻回到命令行验证。很多人在 IDEA、VS Code 里看到 Git 报错就以为是 IDE 的问题其实底层调用的是同一个 Git。回到命令行跑同样的命令能快速确认是 Git 环境的问题还是 IDE 集成的问题。第三个习惯是清理完环境变量或者配置文件后一定要重启终端。环境变量在终端启动时就会加载你改了系统变量但正在运行的终端窗口还保留着旧值这时候继续测试会以为问题没解决。重启终端或者重新打开 IDE再做验证。第四个习惯是重视 SSH 地址而不是 HTTPS 地址。如果是公司内网自建 GitLab我非常推荐使用 SSH 协议。SSH 一旦配置好就不用来回输入密码也不用担心企业内部的 HTTPS 证书问题。公网平台如果团队用着顺手SSH 也同样是更省心的选择。最后分享一个小技巧如果经常推送大文件直接在仓库根目录维护一份.gitattributes把常见的二进制类型都用 Git LFS 跟踪起来能避免掉一大半网络传输问题。这个文件建议在项目初始化的时候就提交越早越好因为后面再改历史提交里的大文件已经很难清掉了。Git 的网络报错从来都不是什么玄学本质上就是域名、端口、证书、密钥、传输参数这五个环节里的某一个出了问题。只要按照链路一层层往下查绝大多数问题都能在十分钟内定位。希望这组排查方法能让你下次遇到“网络连接失败”的时候不用再靠重启电脑解决。