Git Push 失敗：HTTP 413 Request Entity Too Large 問題排查
在使用 Git 推送包含較大編譯產物的項目時，你是否遇到過 HTTP 413 Request Entity Too Large 錯誤？這通常并不是 Git 的問題，而是 Web 服務器（如 Nginx）拒絕接收大體積請求。本文將通過一個完整案例，演示如何使用 curl 工具驗證服務器限制，最終通過寶塔面板修改 Nginx 配置解決問題，實現大文件 Git 推送成功。適用于使用 Gitblit、Gitea 或任何基于 Nginx 部署的私有 Git 服務環境。
一、問題描述
在使用 Git 推送一個包含編譯產物的倉庫時，推送失敗，報錯如下：
error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly
Git GUI (SourceTree) 中顯示：
POST git-receive-pack (287021804 bytes)
error: RPC failed; HTTP 413
二、初步分析
HTTP 413 代表“請求體過大”，通常是服務端擁有上傳大小限制。可能的源有兩個：
- Git 服務本身限制 (Gitblit/Gitea/GitLab)
- Web 服務器如 Nginx 或 Apache 進行的前置限制
為了確認問題所在，我們進行下面的演示性測試。
三、演示測試: curl 模擬上傳
步驟1: 創建大文件 (300MB)
在 PowerShell 中執行：
fsutil file createnew bigfile.test 314572800
步驟2: 使用 curl.exe 模擬 POST 上傳
curl.exe -v -X POST http://域名/ -H "Expect:" --data-binary "@bigfile.test"
結果：
HTTP/1.1 413 Request Entity Too Large
Server: nginx
確認限制來自 Nginx，Git 本身無問題。
步驟3: 創建小文件 (1KB)
fsutil file createnew smallfile.test 1024
重復 curl POST 測試，結果成功，顯示 Gitblit 網頁內容，證明小文件能正常處理。
四、解決方案：修改 Nginx 配置 (寶塔面板)
操作步驟
-
打開寶塔面板后臺 (http://你的IP:8888)
-
點擊左側「軟件商店」，找到 Nginx
-
點擊「配置修改」或「配置文件」
-
找到
http {塊，加入：client_max_body_size 512m; # 允許最大上傳體積為 512MB -
保存配置
-
回到 Nginx 設置界面，重載配置或重啟 Nginx
實際配置示意圖
http {include mime.types;default_type application/octet-stream;client_max_body_size 512m;sendfile on;keepalive_timeout 60;...
}
五、重試 Git 推送
配置重載后，再次執行 Git push，推送包大小達 274MB，已成功，問題解決。
六、總結與建議
| 操作步驟 | 結果 |
|---|---|
| curl 模擬上傳 bigfile.test | 報 413，確認 Nginx 限制 |
| curl 上傳 smallfile.test | 成功返回 Gitblit 頁面 |
| 修改 Nginx 配置 | 重載后 push 成功 |
建議:
- 盡量不要推送編譯產物 (.dll/.lib/.pdb)
- 使用
.gitignore或 Git LFS 管理大文件 - 一旦推送無法成功，優先檢查 Nginx/選項配置
