Windows下用Git上传本地文件，最让人抓狂的往往不是命令敲错，而是所有配置都正常、本地提交也顺利，偏偏在push那一步卡住，报出一堆看不懂的错误。我前阵子帮某开发者处理过一个典型的案例：他的Windows电脑上有一个项目目录，代码改完后想推到远端仓库，结果反复出现Failed to connect、RPC failed; curl 56这类提示，过了高峰期又偶尔能通，根本没法稳定工作。
这种“时好时坏、一传大文件就断”的现象，在他那个网络环境下非常典型。很多人第一反应是去改Git的配置参数，比如调大http.postBuffer、换SSH协议，但改完之后发现还是老样子。实际上，问题的根子往往不在Git本身，而在操作系统到远端仓库之间的那条链路上。这篇博文就把这次完整的上传排查和实操过程写出来，覆盖Windows环境配置、传输参数调整、仓库初始化到推送的完整闭环，最后附上常见问题速查表。不管你是初学者还是被这个问题折磨过的老手，按这个顺序走一遍，基本能把坑填平。
1. 先别急着调参数：把场景和问题拆清楚
1.1 这类问题长什么样
Git上传失败从外在表现上大概有三类。
第一类是连接阶段直接失败，报fatal: unable to access 'https://...': Failed to connect to ... port 443: Timed out。这类错误说明TCP握手都没完成，问题出在网络路径上，跟仓库内容、文件大小没有半毛钱关系。
第二类是认证阶段出问题，比如fatal: Authentication failed for 'https://...'。这类最常见的原因是密码改了、令牌过期，或者Windows凭据管理器里缓存了旧凭据。
第三类是传输中途断掉，典型报错是RPC failed; curl 56 OpenSSL SSL_read: Connection was reset, errno 10054，或者error: RPC failed; HTTP 408。这类说明TCP连接建立了，但数据传着传着被掐断，往往是长连接被中间网络设备重置，或者缓冲区设置不合理导致的。
那个开发者的报错就属于第三类，而且还有个规律：单个几KB的小文件上传偶尔能成功，一上传包含图片、压缩包这种大文件的提交，十次有八次会断。后来的排查方向就很明确了，先排除仓库本身的问题，再检查传输链路和Windows侧的配置。
1.2 问题源头分成两类，别混在一起排查
很多人一遇到Git上传失败，就拼命调Git参数，这是最典型的误区。Git参数只影响Git客户端和服务器之间的交互行为，影响不到操作系统层面的网络连接。所以先花几分钟判断问题属于哪一类，比盲目改配置高效得多。
判断方法很简单，做两个小测试：
第一个测试是网络连通性。打开命令提示符，执行ping <远端仓库域名>，如果丢包严重或者延迟忽高忽低，说明物理链路不稳定。再执行nslookup <远端仓库域名>，确认域名解析出来的IP是预期的，而不是被某些本地策略改写后的异常地址。
第二个测试是仓库可达性。如果远端仓库用的是SSH协议，执行ssh -T git@<仓库域名>，能收到欢迎信息说明认证链路正常。如果用的是HTTPS协议，随便访问一下仓库的网页端，看看能不能正常打开。
这两个测试做完，基本就能把问题归成两类：一类是网络环境导致的连接问题，另一类是仓库配置或认证导致的逻辑问题。前者才需要去调系统网络参数或Git传输参数，后者只需要检查账号凭据和仓库地址。那个开发者的情况是ping正常、网页端能打开，但大文件传输必断，这就锁定在了传输链路的稳定性上。
注意：如果你发现ping域名都不通，或者解析出来的IP有问题，那Git这边改什么都没用，得先解决网络可达性问题。这个顺序不能反。
2. Windows下Git环境配置：很多坑在装好之后才暴露
2.1 Git安装时容易忽略的内置工具链选项
Windows下安装Git，绝大多数人都是默认一路Next。但默认选项里有一个很关键的点：Git Bash提供的是一套类Unix环境，里面内置了SSH客户端、curl、vim等工具。如果你在安装时选择了“Use OpenSSH”而不是Git自带的SSH，就意味着后续SSH操作走的是Windows系统自带的OpenSSH，而不是Git内置的那一套。
这个区别在平时不明显，一旦涉及到密钥路径、known_hosts文件位置、甚至SSH配置文件的写法，两套工具的行为会有细微差异。比如Git自带的SSH默认会把known_hosts放在~/.ssh/known_hosts，而Windows OpenSSH在某些版本下会走到C:\Users\<用户名>\.ssh\known_hosts，如果两边同时存在，就会出现“密钥明明配好了，但SSH连接还是报Host key verification failed”这种灵异问题。
我的建议是，尽量让Git和操作系统用同一套SSH实现。具体做法是在Git安装完成之后，执行git config --global core.sshCommand "ssh"，让Git直接调用系统OpenSSH，避免内置SSH和系统SSH之间的行为差异。如果你更习惯Git Bash里的那一套，那就要确保所有命令都在Git Bash里执行，别在PowerShell和Git Bash之间来回切换，否则很容易遇到环境不一致导致的坑。
另外，安装完Git之后第一件事应该是设置全局用户信息，这不是可选项。执行git config --global user.name "你的名字"和git config --global user.email "你的邮箱"，否则首次提交会报Please tell me who you are，虽然能临时用-c参数绕过，但后面每次提交都会很痛苦。
2.2 换行符CRLF转LF的坑，以及它如何影响上传
Windows下用Git，还有一个默认设置会在你意想不到的时候给你添乱：换行符转换。
Git安装时默认的换行符选项是Checkout Windows-style, commit Unix-style line endings，也就是checkout时把LF转成CRLF，commit时把CRLF转回LF。这个设计初衷是为了让同一个仓库在Windows和Linux之间切换时不至于乱掉，但实际工作中，它带来的麻烦往往比好处多。
举个实际例子：某开发者把一个包含脚本文件（.sh）和配置文件（.conf）的项目从Windows传到远端，然后有人在Linux机器上拉下来跑，发现脚本直接报bad interpreter: /bin/sh^M错误。原因就是在Windows上提交时，Git把原本的LF转成了CRLF，而CRLF在Linux下会被当成普通字符，解释器就不认了。
这类问题在“上传”这个动作里很隐蔽，因为你本地看文件是正常的，提交日志也显示没有改动，但远端仓库里的内容已经和你本地不一样了。
处理方案有两种。
一种是全局关掉自动转换，设置.gitattributes文件，在里面明确指定哪些文件用LF、哪些文件用CRLF。比如：
* text=auto *.sh text eol=lf *.bat text eol=crlf *.cmd text eol=crlf这种方式最干净，能把规则固化到仓库里，所有协作者拉下来都会遵循同一套规则。
另一种是简单粗暴地在全局配置里关掉转换：git config --global core.autocrlf false。这样Git就不会自动做任何换行符转换，提交什么就是什么。这种方式适合单人使用或团队约定用LF的场景。
我的经验是，如果项目主要是代码文件，直接设成core.autocrlf false最省心。如果团队里有Windows和macOS/Linux混用，还是老老实实建.gitattributes，别指望默认行为能照顾到所有人。
2.3 凭据管理器与认证方式选型
Windows上Git的认证方式五花八门，踩坑概率也很高。默认情况下，Git for Windows会启用Git Credential Manager，它会把凭据存在Windows凭据管理器里，下次推送时自动带上，不用重复输入密码。
听起来很方便，但坑就在这里：如果你的密码改了，或者从密码认证切换到了令牌认证，Git Credential Manager里缓存的老凭据不会自动失效，导致每次推送都报Authentication failed。而且这个报错不会告诉你是凭据过期了，只会让你感觉莫名其妙。
解决办法是主动管理凭据缓存。当认证失败时，打开控制面板 -> 用户账户 -> 凭据管理器，找到git:https://<仓库域名>这一项，直接删除。或者用命令行的方式：
git credential-manager erase然后重新推送，会再次要求输入用户名和密码，这时候填新凭据就行。
关于选HTTPS还是SSH，我的建议是：如果你只是在Windows上自己用，并且仓库托管平台支持令牌认证，HTTPS加令牌是最省事的组合，因为Windows凭据管理器能记住令牌，体验很顺。如果你要管理多台机器、经常在CI环境里部署，或者对安全性要求更高，那用SSH密钥更合适，因为密钥可以设置密码短语，也可以配置不同的密钥对应不同的平台。
用SSH时要注意密钥权限问题。Windows下很容易忽略这一点，C:\Users\<用户名>\.ssh\目录下的私钥文件如果权限太开放，SSH会直接拒绝使用，报UNPROTECTED PRIVATE KEY FILE。解决办法是右键私钥文件 -> 属性 -> 安全 -> 高级 -> 禁用继承，然后删除所有用户，只保留当前用户的完全控制权限。这一步不做，密钥配得再对也连不上。
注意：HTTPS方式下，不要把密码写死在远程仓库地址里，比如
https://用户名:密码@仓库地址这种格式。一旦仓库地址被分享出去，密码就等于泄露了。用令牌并配合凭据管理器才是正道。
3. 受限网络环境下的传输调整实践
3.1 HTTPS还是SSH，在这个场景下怎么选
Windows下Git上传，很多人纠结用HTTPS还是SSH。这两种协议在正常网络下差异不大，但在网络受限、传输不稳定的场景下，选择会直接影响成败。
HTTPS协议走的是443端口，和普通网页访问共用一条路，中间设备对它比较友好，不容易被特殊策略拦截。但HTTPS的缺点是传输大对象时，如果缓冲区设置不当，很容易出现RPC failed; curl 56这类错误。SSH协议走的是22端口，数据全部封装在SSH隧道里，对网络抖动更敏感，但一旦连上，传输过程的稳定性往往优于HTTPS，因为它自带压缩机制，并且不容易被HTTP中间层干扰。
在那个开发者的场景里，网页端访问正常，但HTTPS大文件传输必断。我当时没有急着切换协议，而是先让他确认了一个信息：22端口是否通畅。方法是执行ssh -T -p 22 git@<仓库域名>，如果能正常返回欢迎信息，说明SSH路径是通的；如果连接超时，说明出口方向把22端口限制了，这时候就只能用HTTPS并配合参数调整。
结论是：能走SSH就优先SSH，因为传输稳定性更好；走不了SSH再回头调HTTPS的传输参数。别一上来就两套方案来回试，浪费时间。
3.2 几个真正管用的传输参数调整
如果确定要留在HTTPS这条路，下面几个参数是真正经过验证有效的，不是网上那些传烂了的万能药方。
第一个是http.postBuffer。这个参数控制Git在推送时单个HTTP POST请求的数据缓冲区大小，默认值是1MB。当你的提交包含大文件时，Git会把数据拆成多个请求，如果缓冲区太小，大文件版本数据很容易在传输中途被中断。调整方法是：
git config --global http.postBuffer 524288000这里设置成500MB，给大文件足够的缓冲空间。注意不是越大越好，超过这个值反而可能触发中间设备的流控策略，导致更多重置。
第二个是http.version。Git默认使用HTTP/1.1，但某些中间网络设备对HTTP/1.1的长连接支持不完善，会导致传输中途重置。可以把Git强制切到HTTP/1.0试试：
git config --global http.version HTTP/1.1如果还断，就改成HTTP/1.0。HTTP/1.0每次请求都重新建立连接，传输效率低一些，但兼容性更好。实测下来，很多“连接被重置”问题在切到HTTP/1.1并配合postBuffer调大后就消失了。
第三个是http.lowSpeedLimit和http.lowSpeedTime。Git默认在传输速度低于某个阈值持续一段时间后，会主动断开连接。如果你那边的网络带宽不高，或者传输大文件时速度波动大，很容易触发这个机制。把阈值调低、时间放宽：
git config --global http.lowSpeedLimit 1000 git config --global http.lowSpeedTime 300意思是传输速度低于1000字节/秒持续300秒才断开，这个参数组合对慢速网络非常友好。
第四个是关闭SSL验证，但这招要慎用。如果内网的CA证书不被Git信任，可以临时用git config --global http.sslVerify false关闭验证。但这意味着中间人可以解密你的数据，属于“一时爽、过后怕”的操作。只在调试阶段临时用，调试完必须改回来。
提示：以上参数都可以不带
--global只对当前仓库生效，比如你在某个项目里执行git config http.postBuffer 524288000，就只对这个仓库起作用。建议先做仓库级配置，确认有效后再考虑全局生效，避免影响其他项目的正常行为。
3.3 大仓库上传的增量优化策略
除了调整Git参数，还有一类问题是仓库本身就太大了，比如历史提交里包含了几百MB的二进制文件，新克隆下来的仓库体积就得按GB算。这种仓库不管你怎么调参数，首次完整上传都大概率会断。
解决办法是改变推送策略，不要一次性把整个历史推上去。有三个实用技巧。
第一个技巧是浅推送。新建一个不带历史提交的本地仓库，把当前文件作为一次全新提交，然后推送到远端。操作方式：
git init git add . git commit -m "initial import" git remote add origin <远端地址> git push -u origin master这样推送的数据量就只是当前文件快照，而不是全部历史，传输成功率大大提升。代价是丢了历史记录，适合旧仓库迁移到新平台或者历史不重要的情况。
第二个技巧是分批推送。如果历史不能丢，可以先把旧仓库的全部历史推上去，然后把当前工作区的新提交再推上去。做法是先创建一个空分支推送历史，再切回主分支推送增量：
git checkout --orphan temp_branch git commit -m "backup history" git push origin temp_branch git checkout master git push origin master这个方法的本质是先把大体积的历史数据单独走一趟，避免和增量提交混在一起，减少单次传输的数据量。
第三个技巧是使用git filter-repo这类工具，把大文件从历史里剔除掉，只保留小文件的历史记录。这个操作相对复杂，但对仓库长期健康最有利。如果项目里已经误提交过大文件，更推荐直接用这个方法清理历史，而不是反复调整传输参数。
4. 完整实操：从新建本地仓库到推送远端
4.1 本地仓库初始化的标准动作
拿那个开发者的场景举例，他的项目目录是D:\work\模拟项目X，里面有源码、文档和一个10MB左右的资源包。目标是把这个目录完整推送到远端的一个空仓库。
第一步，进入目录，初始化仓库：
cd D:\work\模拟项目X git init这一步会创建一个.git子目录，存放所有版本信息。注意，执行git init之前一定要确认当前目录是正确的，别在上级目录甚至用户目录下执行，否则会把整个目录树纳入版本管理。
第二步，创建.gitignore文件。这一步很多人忽略，但极其重要。Windows下编译产生的bin、obj目录，IDE的.vs目录，以及日志文件、临时文件，都不应该进版本库。一个合理的.gitignore示例：
bin/ obj/ *.user *.suo .vs/ *.log第三步，把文件加入暂存区并提交：
git add . git commit -m "项目初始化提交"第三步执行完，本地版本库就建立好了。执行git log --oneline能看到一条提交记录，说明本地提交成功。
4.2 关联远端仓库的三种写法
本地仓库和远端建立关联，是上传前最后一道工序。执行：
git remote add origin <远端地址>这里要注意远端地址的写法。HTTPS地址、SSH地址和带凭据的地址行为不一样。
# HTTPS地址，推荐 git remote add origin https://github.com/用户名/仓库名.git # SSH地址，推荐 git remote add origin git@github.com:用户名/仓库名.git # 带凭据的HTTPS地址，绝对不推荐 git remote add origin https://用户名:密码@github.com/用户名/仓库名.git关联之后，执行git remote -v确认地址无误。如果写错了，用git remote set-url origin <新地址>修改，不需要重新add。
分支命名也要注意。新版Git默认初始分支是master，但很多远端仓库平台现在默认用main。推送之前先确认一下远端默认分支是什么，避免推上去之后发现分支名对不上。一种稳妥的做法是在本地初始化时就指定分支名：
git init -b main这样本地分支就叫main，和大多数远端平台的默认分支对齐。
4.3 推送命令的准确写法
关联好远端之后，执行推送：
git push -u origin main-u参数的作用是把本地分支和远端分支建立跟踪关系，之后直接执行git push就能推送到对应的远端分支，不需要每次指定分支名。
如果推送过程中遇到连接被重置，按照第3.2节的参数调整思路处理。这里有一个经验性的执行顺序：
- 先执行
git config --global http.postBuffer 524288000调大缓冲。 - 再执行
git config --global http.version HTTP/1.1固定HTTP版本。 - 如果还断，执行
git config --global http.lowSpeedLimit 0，关闭低速断开机制。 - 如果还断，再考虑切换协议或者分批推送。
整个过程中，一次只调整一个参数，然后重新推送测试。别一次性把所有参数都改了，否则无法判断是哪个参数真正起了作用。
4.4 上传后的验证步骤
推送成功不代表事情就结束了。最后一步验证很有必要，尤其是Windows环境下换行符转换可能已经悄悄改了文件内容。
验证分三层：
第一层是本地确认。在项目目录执行git status，看到Your branch is up to date with 'origin/main'说明本地和远端同步。
第二层是远端确认。登录仓库平台网页端，查看文件列表，确认关键文件存在。这一步可以发现分支名对不上、文件缺失这类问题。
第三层是完整性确认。如果项目包含大文件，本地执行：
git fsck --full这个命令会检查对象数据库的完整性，确保没有悬空对象或损坏的提交。如果输出正常，说明传输过程中文件没有损坏。
我在那个开发者的项目里就遇到过第三层验证发现问题的情况：推送显示成功，但git fsck报了一个dangling commit，说明有一次提交在传输过程中没有被完整写入。这种问题不检查根本发现不了，但之后在别的机器上克隆这个仓库时，就会莫名其妙少东西。
5. 常见问题速查表与避坑清单
5.1 速查表：症状、原因、处理
| 报错信息或现象 | 可能原因 | 处理方式 |
|---|---|---|
Failed to connect ... Timed out | 网络路径不通或域名解析异常 | 检查网络连通性、DNS解析、目标端口是否可达 |
Authentication failed | 凭据过期或缓存了旧凭据 | 打开Windows凭据管理器删除旧凭据后重新认证 |
RPC failed; curl 56 | 传输中途连接被重置 | 调大http.postBuffer，固定http.version为HTTP/1.1 |
RPC failed; HTTP 408 | 请求超时 | 调低http.lowSpeedLimit，放宽http.lowSpeedTime |
UNPROTECTED PRIVATE KEY FILE | SSH私钥文件权限过宽 | 修改文件权限，只保留当前用户的完全控制权限 |
bad interpreter: /bin/sh^M | Windows换行符CRLF混入Linux脚本 | 设置.gitattributes或关闭core.autocrlf |
error: failed to push some refs | 本地和远端历史不一致 | 先执行git pull --rebase再推送 |
| 推送显示成功但文件缺失 | 分支名不对或推错了分支 | 用git branch -a检查分支，确认远端分支名 |
5.2 踩过几次坑之后的避坑清单
Windows下Git上传的坑，总结下来有六条。每一条都是我用实际教训换来的，写在这里希望能帮你跳过。
第一条，永远不要在仓库地址里写密码。凭据管理器存在的意义就是让你不用把密码暴露在明处。地址一旦进了git remote -v或.git/config，就等于把密码写进了项目文件，这种泄露是悄无声息的。
第二条，.gitignore文件要在第一次git add之前创建。如果你先执行了git add .把一堆临时文件加进去了，再去创建.gitignore，那些文件已经进了暂存区，.gitignore对它们不起作用，你得手动git rm --cached才能移除。
第三条，Windows下提交前先确认换行符设置。在项目根目录执行git config core.autocrlf，如果输出是true，并且项目里包含脚本类文件，强烈建议用.gitattributes来明确规则，别依赖默认行为。
第四条，遇到网络问题先区分环节。先ping、再nslookup、再ssh -T或网页访问，确认是哪一层出了问题再动手改配置。盲目调参数不仅浪费时间，还可能把原本正常的仓库配置改坏。
第五条，大仓库优先用SSH协议。如果22端口通畅，SSH在传输稳定性上的优势是实打实的。只有在SSH不通的情况下，才回到HTTPS做参数调整。
第六条，推送成功后立刻做git fsck --full完整性检查。尤其是有大文件的项目，这个检查能发现很多传输过程中的隐性损坏。别等别人来报问题的时候才去查，那时候排查成本翻倍。
七条，Windows凭据管理器里的旧凭据不会自动刷新。一旦换了密码或令牌，记得主动去删掉旧凭据，否则你会被“配置全对但认证失败”折磨很久。
一点实际操作后的体会
这次处理的案例，最后定位到的是网络链路加上Git缓冲区设置两个因素叠加。单独调大缓冲区只能解决一部分问题，把HTTP版本固定、低速断开机制关掉之后，大文件传输才真正稳定下来。整个过程下来，我的感受是：Git上传失败不是一个“玄学”问题，每一步都有明确的排查方法，关键是要沉住气，一层一层拆开看，别被报错信息吓到。
另外有个小技巧值得一提：如果你经常需要在Windows和类Unix系统之间切换项目，可以在Git Bash里配置一个别名，把常用的排查命令打包成一条，比如git-debug，一次性输出当前仓库配置、远端地址、传输参数和认证状态。我自己的做法是把这段逻辑写进.bashrc，省去了每次手动敲一堆命令的时间。这个习惯养成后，排查效率能提升不少。
