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

  • Git LFS 原始的 v1 API 不受支持。
  • Git LFS 请求使用 HTTPS 凭据，这意味着您应该使用 Git 凭据存储。
  • 群组 wiki 不支持 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。

  • Git LFS 支持未在极狐 GitLab 服务器上启用。与您的极狐 GitLab 管理员核实为何服务器未启用 Git LFS。请参阅 LFS 管理文档了解启用 Git LFS 支持的说明。

  • Git LFS 客户端版本不受极狐 GitLab 服务器支持。您应该：

    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'

推送时缺少 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 仓库，可以这样做。如果您使用外部 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 跟踪文件。

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

  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 文件中的规则时。只有当 LFS 文件符合 .gitattributes 中的规则时，它们才会自动检出。

极狐 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 文件：

{{< tabs >}}

{{< tab title=”With Git” >}}

  1. 克隆您的仓库：

    git clone <repository>
cd repository

  2. 创建一个空的 .gitattributes 文件：

    touch .gitattributes
git add .gitattributes
git commit -m "Add empty .gitattributes file to root directory"
git push

{{< /tab >}}

{{< tab title=”In the UI” >}}

  1. 选择 搜索或转到 并找到您的项目。
  2. 选择加号图标（+）和 新文件。
  3. 在 文件名 字段中输入 .gitattributes。
  4. 选择 提交更改。
  5. 在 提交消息 字段中输入提交消息。
  6. 选择 提交更改。

{{< /tab >}}

{{< /tabs >}}