Git Push 卡住：POST git-receive-pack (chunked) 问题处理

📋 问题概述

在使用 Git 推送代码到远程仓库时，特别是当提交包含大文件（如图片、音频、视频等）时，经常会遇到推送过程卡住的情况。

典型症状

Counting objects: 21, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (21/21), done.
Writing objects: 100% (21/21), 1018.52 KiB | 17.87 MiB/s, done.
Total 21 (delta 7), reused 0 (delta 0)
# 卡在这里，没有进一步输出

使用 git push -v 查看详细信息时显示：

POST git-receive-pack (chunked)

🔍 问题原因分析

根本原因

这是 Git 在使用 HTTPS 协议时的一个已知问题：

分块编码问题：当上传内容超过预设大小限制时，Git 会使用 HTTP 分块编码（chunked encoding）
服务器兼容性：某些 Git 服务器对分块编码的支持不完善，导致传输中断
缓冲区限制：Git 默认的 HTTP 缓冲区大小有限，大文件传输时容易超出限制

触发条件

推送包含大文件的提交（通常 > 1MB）
使用 HTTPS 协议连接远程仓库
网络连接不稳定或延迟较高

🛠️ 解决方案

方案一：增加 HTTP 缓冲区大小（推荐）

首先了解当前缓冲区设置

在修改配置之前，建议先查看当前的缓冲区设置：

# 查看全局 http.postBuffer 配置
git config --global --get http.postBuffer
 
# 查看当前仓库的 http.postBuffer 配置
git config --get http.postBuffer
 
# 查看所有 HTTP 相关配置
git config --list | grep http

默认值说明：

Git 的默认 http.postBuffer 大小通常是 1MB（1048576 字节）
如果命令没有返回值，说明使用的是 Git 内部默认值

1. 命令行方式

# 设置当前仓库的 HTTP 缓冲区为 500MB（524288000 字节）
git config http.postBuffer 524288000
 
# 设置全局配置（影响所有仓库）
git config --global http.postBuffer 524288000

数值说明：

524288000 字节 = 500MB
计算公式：500 × 1024 × 1024 = 524,288,000 字节
可根据实际需要调整大小（建议范围：100MB - 1GB）

2. 配置文件方式

编辑项目根目录下的 .git/config 文件：

vim .git/config

在文件末尾添加或修改 [http] 部分：

[http]
    postBuffer = 524288000

方案三：使用 SSH 协议（根本解决）

HTTPS 协议容易出现分块编码问题，改用 SSH 协议可以避免此问题：

# 查看当前远程仓库配置
git remote -v
 
# 将 HTTPS 地址改为 SSH 地址
git remote set-url origin git@github.com:username/repository.git

注意：使用 SSH 需要预先配置 SSH 密钥。

方案四：分批推送大文件

如果单次推送的文件过大，可以考虑分批推送：

# 推送单个文件或小批量文件
git add file1.jpg
git commit -m "Add file1"
git push
 
git add file2.mp3
git commit -m "Add file2"
git push

⚡ 高级解决方案

1. 调整网络超时设置

# 增加 HTTP 超时时间（秒）
git config --global http.timeout 300
 
# 设置低速传输的时间限制
git config --global http.lowSpeedLimit 1000
git config --global http.lowSpeedTime 300

2. 使用 Git LFS 管理大文件

对于经常需要提交大文件的项目，建议使用 Git LFS：

# 安装 Git LFS
git lfs install
 
# 跟踪大文件类型
git lfs track "*.png"
git lfs track "*.mp3"
git lfs track "*.mp4"
 
# 提交 .gitattributes 文件
git add .gitattributes
git commit -m "Add Git LFS tracking"

3. 压缩和优化

# 启用压缩
git config --global core.compression 9
 
# 垃圾回收和优化
git gc --aggressive --prune=now

🧮 缓冲区大小计算与选择

如何确定合适的缓冲区大小

评估项目文件大小：

# 查看仓库中最大的文件
find . -type f -exec ls -la {} \; | sort -nrk 5 | head -10
 
# 查看特定类型文件的大小
find . -name "*.png" -exec ls -lh {} \;
find . -name "*.mp3" -exec ls -lh {} \;

计算推荐缓冲区大小：

推荐缓冲区 = 最大单文件大小 × 2 到 5 倍

例如：最大文件 50MB
推荐设置：100MB - 250MB
对应数值：104857600 - 262144000 字节

常用数值快速参考：

# 50MB
git config http.postBuffer 52428800
 
# 100MB
git config http.postBuffer 104857600
 
# 200MB
git config http.postBuffer 209715200
 
# 500MB（推荐）
git config http.postBuffer 524288000
 
# 1GB（大型项目）
git config http.postBuffer 1073741824

性能考虑

内存使用：缓冲区会占用系统内存，设置过大可能影响性能
网络环境：网络较慢时，适当增大缓冲区有助于稳定传输
团队协作：建议团队统一缓冲区设置，避免不同成员遇到不同问题

📊 配置参数说明

参数	说明	默认值	推荐值	单位	换算
`http.postBuffer`	HTTP POST 缓冲区大小	1048576 (1MB)	524288000 (500MB)	字节	500MB = 524,288,000 字节
`http.timeout`	HTTP 操作超时时间	无限制	300	秒	5分钟
`http.lowSpeedLimit`	低速传输阈值	0	1000	字节/秒	1KB/s
`http.lowSpeedTime`	低速传输时间限制	0	300	秒	5分钟

常用缓冲区大小参考

文件大小范围	推荐缓冲区设置	数值（字节）	适用场景
< 10MB	默认设置	1048576	普通代码项目
10MB - 100MB	100MB	104857600	包含图片的项目
100MB - 500MB	500MB	524288000	多媒体项目
> 500MB	1GB	1073741824	大型文件项目

🎯 最佳实践

1. 文件管理建议

避免在代码仓库中存储大型二进制文件
图片文件：考虑压缩或转换格式（PNG → JPG）
媒体文件：上传到 CDN 或对象存储，在代码中使用链接引用
文档文件：使用 Markdown 等文本格式替代 Word/PDF

2. 仓库结构优化

project/
├── src/           # 源代码
├── docs/          # 文档（文本格式）
├── assets/        # 小型资源文件
└── .gitignore     # 忽略大文件

3. .gitignore 配置示例

# 大型文件
*.mov
*.mp4
*.avi
*.zip
*.tar.gz
 
# 构建产物
dist/
build/
node_modules/
 
# 日志文件
*.log
logs/

🔧 故障排查步骤

1. 检查当前配置

# 查看当前所有 Git 配置
git config --list
 
# 专门查看 HTTP 相关配置
git config --list | grep http
 
# 检查全局缓冲区设置
git config --global --get http.postBuffer
 
# 检查当前仓库缓冲区设置
git config --get http.postBuffer
 
# 查看仓库大小
du -sh .git/
 
# 查看最近提交的文件大小和详情
git show --stat
 
# 检查最近提交中的大文件
git show --name-only

2. 配置验证

# 验证配置是否生效
git config --get-regexp http.*
 
# 检查特定配置的来源（全局/本地/系统）
git config --show-origin --get http.postBuffer
 
# 列出所有配置文件位置
git config --list --show-origin | grep http

2. 逐步调试

# 启用详细输出
git push --verbose --progress
 
# 测试网络连接
git ls-remote origin
 
# 检查 SSH 连接（如果使用 SSH）
ssh -T git@github.com

3. 临时解决方案

如果急需推送，可以尝试：

# 强制推送（谨慎使用）
git push --force-with-lease
 
# 或者重置到之前的提交，分批推送
git reset --soft HEAD~1

⚠️ 注意事项

耐心等待：设置缓冲区后，大文件推送仍需要时间，请耐心等待
网络环境：确保网络连接稳定，避免在网络高峰期推送大文件
仓库大小：GitHub 等平台对仓库大小有限制，避免滥用
团队协作：团队项目中使用大文件前应与团队成员商议

缓冲区设置相关注意事项

内存影响：http.postBuffer 设置过大会占用更多系统内存，建议根据实际需要设置
配置优先级：本地仓库配置 > 全局配置 > 系统默认配置
配置验证：修改配置后建议先用小文件测试，确认配置生效
重置配置：如需重置为默认值，使用 git config --unset http.postBuffer
团队统一：建议团队成员使用相同的缓冲区设置，避免环境差异导致的问题

Git Push 卡住：POST git-receive-pack (chunked) 问题完整解决指南