Git LFS 故障排除

使用 Git LFS 时，你可能会遇到以下问题。

• Git LFS 原始 v1 API 不受支持。
• Git LFS 请求使用 HTTPS 凭据，这意味着你应该使用 Git 凭据存储。
• 群组维基 不支持 Git LFS。

错误：仓库或对象未找到

此错误可能由以下几种原因造成：

• 你没有权限访问某些 LFS 对象。确认你有权限推送或拉取项目。
• 项目无权访问 LFS 对象。你想要推送（或拉取）的 LFS 对象对项目不再可用。在大多数情况下，该对象已被从服务器移除。
• 本地 Git 仓库正在使用已弃用的 Git LFS API 版本。更新你的本地 Git LFS 副本并重试。

<url> 的状态无效：501

Git LFS 将失败记录记录到日志文件中。要查看此日志文件：

1. 在你的终端窗口中，进入项目目录。

2. 运行以下命令查看最近的日志文件：

   git lfs logs last

这些问题可能导致 501 错误：

• 你的项目设置中未启用 Git LFS。检查你的项目设置并启用 Git LFS。

• GitLab 服务器上未启用 Git LFS 支持。询问你的 GitLab 管理员为什么服务器上未启用 Git LFS。有关如何启用 Git LFS 支持的说明，请参阅 LFS 管理文档。

• GitLab 服务器不支持 Git LFS 客户端版本。你应该：

  1. 使用 git lfs version 检查你的 Git LFS 版本。
  2. 使用 git lfs -l 检查项目的 Git 配置中是否有已弃用 API 的痕迹。如果你的配置设置了 batch = false，请删除该行，然后更新你的 Git LFS 客户端。GitLab 仅支持 1.0.1 及更高版本。

推送对象时总是需要凭据

Git LFS 对每个对象的每次推送都使用 HTTP 基本身份验证来验证用户，因此需要用户的 HTTPS 凭据。默认情况下，Git 支持记住你使用的每个仓库的凭据。有关更多信息，请参阅 官方 Git 文档。

例如，你可以告诉 Git 在你预期推送对象的一段时间内记住你的密码。此示例会记住你一小时的凭据（3600 秒），一小时后你必须重新验证身份：

git config --global credential.helper 'cache --timeout=3600'

要存储和加密凭据，请参阅：

• macOS：使用 osxkeychain。
• Windows：使用 wincred 或 Microsoft 的 Windows Git 凭据管理器。

要了解有关存储用户凭据的更多信息，请参阅 Git 凭据存储文档。

推送时缺少 LFS 对象

GitLab 在推送时检查文件以检测 LFS 指针。如果检测到 LFS 指针，GitLab 会尝试验证这些文件是否已存在于 LFS 中。如果你使用单独的服务器来托管 Git LFS，并且遇到此问题：

1. 确认你已在本地安装 Git LFS。
2. 考虑使用 git lfs push --all 进行手动推送。

如果你将 Git LFS 文件存储在 GitLab 之外，你可以在你的项目中 禁用 Git LFS。

外部托管 LFS 对象

你可以通过设置自定义 LFS URL 来外部托管 LFS 对象：

git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs

如果你将 LFS 数据存储在设备上（如 Nexus Repository），你可能需要这样做。如果你使用外部 LFS 存储，GitLab 无法验证 LFS 对象。如果你启用了 GitLab LFS 支持，推送将会失败。

要停止推送失败，你可以在 项目设置 中禁用 Git LFS 支持。但是，这种方法可能不是理想的，因为它也会禁用 GitLab LFS 功能，例如：

• 验证 LFS 对象。
• GitLab UI 对 LFS 的集成。

推送 LFS 对象时出现 I/O 超时

如果你的网络状况不稳定，Git LFS 客户端在尝试上传文件时可能会超时。你可能会看到如下错误：

LFS: Put "http://example.com/root/project.git/gitlab-lfs/objects/<OBJECT-ID>/15":
read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout
error: failed to push some refs to 'ssh://example.com:2222/root/project.git'

要解决此问题，将客户端活动超时设置为一个更高的值。例如，将超时设置为 60 秒：

git config lfs.activitytimeout 60

遇到 n 个本应是指针但不是的文件

此错误表明仓库应该使用 Git LFS 跟踪文件，但没有。问题 326342（在 GitLab 16.10 中修复）是此问题的一个原因。

要解决此问题，迁移受影响的文件并将它们推送到仓库：

1. 将文件迁移到 LFS：

   git lfs migrate import --yes --no-rewrite "<your-file>"

2. 推送回你的仓库：

   git push

3. 可选。清理你的 .git 文件夹：

   git reflog expire --expire-unreachable=now --all
   git gc --prune=now

LFS 对象未自动检出

你可能会遇到 Git LFS 对象未自动检出的问题。当发生这种情况时，文件存在但包含指针引用而不是实际内容。如果你打开这些文件，可能会看到一个 LFS 指针，而不是预期的文件内容，如下所示：

version https://git-lfs.github.com/spec/v1
oid sha256:d276d250bc645e27a1b0ab82f7baeb01f7148df7e4816c4b333de12d580caa29
size 2323563

当文件名与 .gitattributes 文件中的规则不匹配时，会出现此问题。只有当文件与 .gitattributes 中的规则匹配时，LFS 文件才会自动检出。

在 git-lfs v3.6.0 中，此行为发生了变化，并且 LFS 文件的匹配方式得到了优化。

GitLab Runner v17.7.0 升级了默认的辅助镜像以使用 git-lfs v3.6.0。

为了在不同操作系统上保持一致的行为（这些操作系统可能具有不同的大小写敏感性），请调整你的 .gitattributes 文件以匹配不同的大小写模式。

例如，如果你有名为 image.jpg 和 wombat.JPG 的 LFS 文件，在你的 .gitattributes 文件中使用不区分大小写的正则表达式：

*.[jJ][pP][gG] filter=lfs diff=lfs merge=lfs -text
*.[jJ][pP][eE][gG] filter=lfs diff=lfs merge=lfs -text

如果你只在区分大小写的文件系统上工作，例如大多数 Linux 发行版，你可以使用更简单的模式。例如：

*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text

警告：可能的 LFS 配置问题

你可能会在 GitLab UI 中看到如下警告：

Possible LFS configuration issue. This project contains LFS objects but there is no .gitattributes file.
You can ignore this message if you recently added a .gitattributes file.

当 Git LFS 已启用并包含 LFS 对象，但在你的项目根目录中未检测到 .gitattributes 文件时，会出现此警告。Git 支持将 .gitattributes 文件放在子目录中，但 GitLab 只在根目录中检查此文件。

解决方法是在根目录中创建一个空的 .gitattributes 文件：