如何通过GitLab API上传大于1GB的大型二进制文件并最小化额外处理

方案1：小文件无临时文件直传（单文件≤实例单文件上传限制时适用） #

GitLab文件API要求文件内容必须以base64编码提交，你之前的写法不生效是因为curl的--data-urlencode无法直接识别进程替换的虚拟文件描述符，可改用管道+jq的方式实现零临时文件传输：

# 注意替换尖括号内的占位符
base64 -w0 binary_archive.tgz | jq -Rs '{
  branch: "main",
  content: .,
  commit_message: "上传二进制压缩包",
  encoding: "base64"
}' | curl --request POST \
  --header "PRIVATE-TOKEN: <你的GitLab访问令牌>" \
  --header "Content-Type: application/json" \
  --url "https://<你的GitLab实例地址>/api/v4/projects/<项目ID>/repository/files/<文件在仓库的存储路径>" \
  --data @-

注意 #

绝大多数GitLab实例的单文件上传上限为100MB，1GB的二进制包无法通过该方法上传，建议使用方案2。

方案2：1GB大文件最优解：手动走LFS协议上传 #

无需克隆仓库、无临时文件、不会增大仓库体积，完全符合你的需求，操作步骤如下：

1. 本地计算二进制包的LFS元数据，替换命令中的文件名即可
   • 计算SHA256哈希：sha256sum binary_archive.tgz | awk '{print $1}'
   • 计算文件字节数：stat -c%s binary_archive.tgz
2. 校验LFS对象是否已存在于GitLab中
   调用LFS批量校验接口，替换占位符后执行：

   curl --request POST \
     --header "PRIVATE-TOKEN: <你的GitLab访问令牌>" \
     --header "Content-Type: application/vnd.git-lfs+json" \
     --url "https://<你的GitLab实例地址>/api/v4/projects/<项目ID>/lfs/objects/batch" \
     --data '{
       "operation": "upload",
       "transfers": ["basic"],
       "objects": [
         {
           "oid": "<第一步计算得到的SHA256哈希>",
           "size": <第一步计算得到的文件字节数>
         }
       ]
     }'
   

   • 如果返回结果中对应对象的actions字段存在upload属性，复制该属性下的href上传地址和所有header值，执行第三步
   • 如果没有upload属性，说明该文件已经上传到LFS存储，直接跳第四步
3. 上传二进制包到LFS存储
   替换占位符后执行，直接传输原二进制文件无需编码：

   curl --request PUT \
     --header "<第二步拿到的所有请求头，每行一个--header参数>" \
     --upload-file binary_archive.tgz \
     "<第二步拿到的LFS上传地址>"
   

4. 提交LFS指针到GitLab仓库
   LFS指针仅几十字节，直接用普通文件API提交即可，无需处理原文件：

   curl --request POST \
     --header "PRIVATE-TOKEN: <你的GitLab访问令牌>" \
     --header "Content-Type: application/json" \
     --url "https://<你的GitLab实例地址>/api/v4/projects/<项目ID>/repository/files/<文件在仓库的存储路径>" \
     --data '{
       "branch": "main",
       "content": "version https://git-lfs.github.com/spec/v1\noid sha256:<第一步计算的SHA256哈希>\nsize <第一步计算的文件字节数>\n",
       "commit_message": "上传二进制压缩包（LFS格式）"
     }'
   

内容的提问来源于stack exchange，提问作者Mr. Tao