Git 拉取文件不完整问题

By | 2025-08-02

解决 Git 拉取文件不完整问题：Git LFS 详解与使用指南

问题引入

今天在使用 Git 拉取代码时，遇到过这样的问题：

  • JS、CSS、IMG 等文件只有几 KB，甚至几字节，而不是完整的文件！？

这通常是因为项目使用了 Git LFS（Large File Storage），但你的环境未正确配置它。
本文将详细介绍 Git LFS 是什么、如何安装和使用。

1. 什么是 Git LFS？

Git 本身适合管理文本文件（如代码），但对大文件（图片、视频、数据集、二进制文件等）支持较差。如果直接提交大文件到 Git，会导致：

  • 仓库体积暴增，克隆变慢。
  • 历史记录臃肿，难以维护。

Git LFS（Large File Storage） 是 Git 的扩展，用于高效管理大文件。它的工作原理：

  1. 存储大文件在远程 LFS 服务器（如 GitHub、GitLab 等）。
  2. 本地仓库仅存储轻量级“指针文件”（几字节），而非真实文件。
  3. 当需要这些文件时（如 git checkout 或 git lfs pull），Git LFS 会自动下载真实文件。

这就是为什么你拉取的 JS、IMG 等文件只有几字节——它们只是 LFS 指针，而非真实文件。

2. 如何安装 Git LFS？

如果你的系统未安装 Git LFS，运行 git lfs 会报错：

git: 'lfs' is not a git command.

解决方法：安装 Git LFS。

（1）Windows / macOS

（2）Linux（Debian/Ubuntu）

# 安装依赖
sudo apt-get install curl

# 添加 Git LFS 仓库并安装
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

（3）验证安装

安装完成后，运行：

git lfs install

如果显示 Git LFS initialized，说明安装成功。

3. 如何使用 Git LFS？

（1）克隆含 LFS 文件的仓库

git clone <仓库地址>  # 会自动拉取 LFS 文件

或手动拉取：

git lfs pull

（2）检查哪些文件由 LFS 管理

git lfs ls-files

会显示类似：

SHA256  abc123...  path/to/image.png

（3）提交大文件到 Git LFS

如果你想在自己的项目中使用 LFS：

git lfs track "*.psd"  # 跟踪 .psd 文件
git lfs track "assets/*.png"  # 跟踪 assets/ 下的 PNG

然后提交 .gitattributes（Git LFS 会自动生成）：

git add .gitattributes
git commit -m "Track large files with LFS"
git push

4. 如果 Git LFS 不可用，如何恢复完整文件？

如果由于某些原因无法安装 Git LFS，你仍然可以手动获取完整文件：

方法 1：直接从远程下载（适用于 GitHub/GitLab）

  • 访问仓库的 Web 界面（如 GitHub）。
  • 找到对应的文件，手动下载并替换本地的小文件。

方法 2：使用 git lfs fetch（如果部分支持）

某些 Git 托管平台可能允许直接下载 LFS 文件：

git fetch origin
git checkout origin/main -- path/to/file.png  # 尝试直接检出文件

方法 3：联系维护者提供非 LFS 版本

如果项目必须依赖 LFS，建议联系作者提供替代方案（如压缩包下载）。

5. 常见问题

Q1：git lfs pull 失败，提示 batch response: Authentication required

  • 原因：Git LFS 需要身份验证。
  • 解决：
    git config --global credential.helper store  # 缓存凭据
git lfs pull  # 重新输入账号密码

Q2：克隆仓库时 LFS 文件没下载

  • 解决：
    git lfs install
git lfs pull

Q3：如何从 Git 历史中彻底删除大文件？

如果误提交大文件到 Git（而非 LFS），可以使用 git filter-repo 清理：

git filter-repo --force --invert-paths --path "large_file.zip"