Git LFS 大檔案下載失敗：怎樣還原內容並保留本地修改？

Git LFS 大檔案下載失敗時，clone 成功不表示大型對象已到工作目錄。先保存修改，確認小型文字檔是 LFS pointer，再分辨下載、權限、配額與 checkout，然後只重試真正需要的檔案。

關鍵要點：

• Git 保存 pointer，LFS 另存相應大型內容。
• 執行會更新工作檔案的命令之前，保護本地修改。
• 先查 attributes 與 include/exclude，才診斷連接。
• 驗收實際檔案與原有工作，不只看 clone 或 pull 成功。

步驟 1：Git LFS 大檔案下載失敗時要保護甚麼？

在受影響儲存庫記錄目前分支或修訂、所需路徑及失敗操作。檢查工作目錄，不丟棄變更；任何寫入內容的操作之前，把無法取代的已修改及未追蹤檔案保存到獲准的安全位置。

git status --short
git --version
git lfs version

LFS pointer 是指向獨立內容的小型文字紀錄。GitHub 文件說明其版本、對象識別及大小欄位；不要編輯 pointer 假造對象、改名繞過，亦不能把它當成原大型檔案已遭破壞的證據。［1］

確認目前修訂中的路徑本應使用 LFS。小文字檔可能本來就是程式碼，不是 pointer；其他分支可引用另一對象。先向項目負責人核實預期，才「還原」內容。

只操作有權使用的普通工作儲存庫；衝突、bare 儲存庫或不明本地修改須另處理。其他應用亦失敗時，先沿裝置故障判斷分支找共同原因，再改儲存庫行為。

步驟 2：Git LFS pointer 檔案符合 attributes 嗎？

確認已安裝 LFS 客戶端，再檢查所需路徑的 attributes。以下名稱是範例，要換成真正追蹤的路徑，公開紀錄不包含私人項目名稱。命令檢查目前路徑是否有 LFS filter 屬性。

git check-attr filter -- assets/needed.bin

本地查看相關 .gitattributes 和下載篩選。Clone 可以有意略過大型內容，include/exclude 亦能排除路徑。這種缺少內容不直接證明網絡失敗，先確認對象屬於預期下載範圍。

屬性發現與 Git/LFS 版本有關。現行 pull 手冊說明 Git 2.42.0 或以後的 index 和屬性限制，尤其涉及 partial clone 和 sparse checkout。依適用版本文件準備所需屬性，不隨便由另一修訂複製，亦不覆蓋已改的屬性檔。［2］

記下版本差異，現行文件不是所有版本都適用。git lfs install 和全儲存庫 migration 不只是檢查，設定可以改配置，應是有意且獲准的動作。

步驟 3：Git LFS pull 錯誤指出哪個階段？

讀第一個相關傳輸錯誤，記下對象、目標路徑、接口角色及失敗階段。Git remote 和 LFS 對象服務相關，卻未必有一樣路由或認證。普通 Git fetch 成功，不代表大型內容服務能完成下一個請求。

觀察	應調查	成功證據
Pointer 保留且未嘗試傳輸	attributes、略過下載、篩選	路徑確已選入 LFS 處理
連接逾時或重設	真正對象傳輸路徑	必需對象已下載
401 或 403	獲准帳戶及 LFS 存取權	該帳戶可取得對象
配額或服務限制	儲存庫負責人的現行政策	負責人解決回應中的限制
伺服器沒有對象	所引用對象有否發佈	負責人提供對應修訂內容
對象本地可用但仍是 pointer	checkout 條件與本地修改	實際內容恢復且修改完整

移除錯誤敏感欄位。不公開含簽名的對象 URL，亦不提交第三方診斷服務；標頭、Cookie、登入憑證、私人主機名稱和內部儲存庫識別也要保護。

一般 Git 平台存取有問題時，可按開發者 GitHub 存取清單處理另一任務，不當作 LFS 對象已取得的證明。Windows 代理不一致時，檢視系統代理設定，保留儲存庫本身的獲准配置。

步驟 4：阻塞是權限、配額或未上載對象嗎？

明確認證失敗應經獲准帳戶與登入流程修正。能查看程式碼，不足以證明對象服務接受此請求。與負責人確認權限，不把 token 放入 remote URL，也不借別人的帳戶。

配額回應由儲存庫負責人或服務管理員處理。各主機與方案限制有別，用目前回應和官方帳戶資料，不硬套舊教程數字。連接變更不會增加儲存或傳輸額度。

若服務端回報沒有對象，保存路徑與修訂，詢問相應 LFS 內容是否已上載。Pointer 無法重建原內容；對不存在對象反覆換連接執行 pull，不是復原方法。

完整性失敗、對象無法解釋地不符或必要修訂改變時停止。不重寫歷史、不做全儲存庫 LFS migration，也不刪光本地對象強求成功，否則會改變內容管理問題並丟失證據。

路徑比較前先說明仍適用的原因，例如獲准對象在傳輸完成前逾時。錯誤已指向權限或內容缺少時，留在該分支處理，不把 VPN 當成每種 LFS 問題的下一步。

步驟 5：另一獲准連接可取得必要對象嗎？

決定只下載，還是下載後填充工作目錄。git lfs fetch 寫入本地對象儲存，git lfs checkout 使用已有對象更新工作檔案；git lfs pull 為目前 ref 合併兩種操作，所以可能更改缺少或 pointer 檔案。［2］［3］

保存修改後，從儲存庫根目錄操作，確認 HEAD 仍對應先前記錄的修訂。範例使用 origin；請改為獲准遠端，兩次嘗試保持相同 remote、修訂及路徑。Include 路徑改為所需檔案；清空 exclude 是針對這條獲准路徑的有意選擇，不代表可繞過組織篩選規則。

重試前檢查 lfs.fetchrecentalways：值為 true 時，fetch 亦會下載近期 ref 或 commit 的對象。以下命令只在本次呼叫關閉這項擴展，不改已保存配置；不要加入 --recent 或其他 ref。fetch 成功才對所選路徑 checkout。［3］

此範例採用 POSIX shell 語法；Windows 可在 Git Bash 執行。

git -c lfs.fetchrecentalways=false lfs fetch \
  --include="assets/needed.bin" --exclude="" origin HEAD &&
  git lfs checkout "assets/needed.bin"

要獨立觀察傳輸與 checkout，可用該版本文件的 fetch 後 checkout 流程。不要預設 fetch --all 是修復，下載全部歷史會擴大任務及消耗不必要額度。對象本地已有時，也不能證明新的網絡傳輸。

指定且獲准的對象傳輸逾時，可用 AethoVPN 在同一電腦比較連接，remote、修訂及篩選保持相同。準備官方 Windows 安裝包、Debian/Ubuntu x64 .deb，或經網站設定指引取得需 Pro/Premium 的 Mac 配置；選 App 目前可用的本國或附近合適位置，連接並開全局模式。再試所選對象，同時確認傳輸和工作目錄內容；配額、未存在對象與儲存庫權限仍屬負責人處理。

新帳戶可透過電郵驗證碼開始 3 天免費 Pro 試用，毋須建立密碼；每位用戶只可獲得一次試用。

連接驗證指引可輔助比較，真正對象內容仍是驗收條件。本機 VPN 不證明遠端 clone、CI 或容器路徑；獨立確認執行環境，沒有相關改善便停止輪換位置。

只使用符合組織政策、當地法律及服務條款的路徑，保留 TLS 和內容驗證。連接恢復卻收到拒絕時，記下新回應，不宣布對象已還原。

步驟 6：Checkout 已恢復內容並保留工作嗎？

確認目標有預期格式及真正內容，而非短 pointer。與項目負責人核對對象與大小資訊，安全時用適合的可信工具開啟檔案。實際檔案可用比沒有錯誤訊息更有力。

再查看 git status --short，與最初紀錄比較。無關已修改與未追蹤檔案應完整，分支及修訂未變。不要為了讓命令成功而強制覆蓋本地編輯。

普通 LFS checkout 不覆蓋已修改檔案，手冊亦有說明。這個保護應用來調查殘留 pointer，不是自動丟棄修改的理由。只有下載完成、工作檔未填充時，分別報告兩項結果。［3］

儲存庫有 Rust Git 依賴時，另外檢查 Cargo fetch 階段；取得依賴源碼不代表 LFS 資產在工作目錄。最後留下去除秘密的事件紀錄：版本、修訂、路徑、接口角色、首個錯誤、對象下載及工作目錄結果。

總結

• 更新 LFS 工作檔案前保存修改。
• 篩選、傳輸、授權、配額與 checkout 分別處理。
• 保持原修訂，只重試必要內容。
• 實際檔案和既有工作完整才結束事故。

常見問題

為何資產變成小型文字檔？

它可能是引用獨立內容的 LFS pointer。先查目前修訂下的路徑與屬性，取得對象，不更改 pointer 本身。［1］

Clone 成功為何大型檔案仍缺少？

Git 儲存庫與 LFS 內容傳輸是不同操作。屬性、略過下載、篩選、權限及傳輸錯誤，都可能在普通 clone 完成後留下 pointer。

Pull 和 fetch 有甚麼分別？

LFS fetch 下載對象，pull 亦按需更新工作副本。若要先看傳輸再寫檔案，應有意選擇流程，並預先保存本地修改。［2］

有儲存庫權限就可讀 LFS 嗎？

能看程式碼並不足以推定權限。核對對象服務登入資料與回應，向管理員確認該帳戶的獲准存取範圍。

VPN 能取消儲存庫配額限制嗎？

配額限制須由負責人或服務管理員解決。改路只能測傳輸，不會增加額度，也不會供應伺服器上缺少的對象。

儲存庫 ZIP 一定包含大型內容嗎？

封存內容視乎託管服務與儲存庫設定。ZIP 成功不代表 LFS 驗收通過，要確認裏面是必要的實際檔案，而非 pointer。

如何確保本地修改保留？

先保存無法取代的工作，對照 checkout 前後狀態。目標已修改或衝突時停止並有意處理，不做全儲存庫 reset 或清理。

免責聲明： 本文只涉及獲准儲存庫與允許連接。遵守當地法律、服務條款及組織政策；範例並非實測結果。

封面歸屬：Git LFS 標誌，Git LFS website contributors；採用 CC BY 4.0 許可。保留原標誌，只等比縮放、置於白色畫布並轉為 WebP；用作識別文章主題，不代表權利方認可。

來源

1. GitHub Docs — About Git Large File Storage — https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage
2. Git LFS — git-lfs-pull — https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-pull.adoc
3. Git LFS — fetch and checkout manuals — https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-fetch.adoc · https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-checkout.adoc

Sources checked 2026 年 10 月 6 日。

延伸閱讀

• 分辨 Rust Git 依賴與 LFS 資產
• 下載對象之前核對平台存取路徑
• 檢視 Windows 代理配置
• 驗證連接後返回原檔案