GitHub Actions上传超2GB Release文件的问题及已尝试方案

我在GitHub Actions上配置了CI/CD工作流，流水线会执行测试与构建操作，创建标签时需要上传Release文件。但遇到问题：构建后的release.zip大小为3.5GB，超过GitHub Releases单个文件不超过2GB的限制，核心原因是包内包含一个3.3GB的文件，该文件必须在应用安装的每台机器本地可用。

应用详情 #

• Windows桌面Python应用
• 构建依赖PyInstaller库
• 构建时将问题文件打包进应用
• 无关联服务器或云服务
• 问题文件原大小约9GB，压缩后3.3GB
• 问题文件通过Git LFS存储

工作流相关任务代码 #

build:
    needs: test
    runs-on: windows-latest

    steps:
      # Checkout
      - uses: actions/checkout@v4
        with:
          lfs: true

      # LFS
      - name: Install Git LFS
        run: |
          choco install git-lfs

      - name: Pull lfs files
        run: |
          git lfs pull

      # Python install
      - name: Set up Python 3.10
        uses: actions/setup-python@v3
        with:
          python-version: "3.10"

      # PyInstaller build
      - name: Build
        run: |
          cd ..
          mkdir build
          cd build
          python -m pip install --upgrade pip
          pip install pyinstaller
          python -m pip install -r ..\requirements.txt
          pyinstaller ..\prod.spec
          xcopy /E /I .\dist\gui\ ..\gui\
          cd ..\
          dir

      # Release
      - name: Extract Tag Name
        id: extract_tag_name
        run: |
          $tagName = $Env:GITHUB_REF -replace 'refs/tags/', ''
          Write-Host "::set-output name=tag_name::$tagName"

      # Zip the output folder
      - name: Zip folder
        if: steps.extract_tag_name.outputs.tag_name != null && steps.extract_tag_name.outputs.tag_name != 'refs/heads/main'
        run: |
          7z a -r release.zip ./gui/

      - name: Create Release
        if: steps.extract_tag_name.outputs.tag_name != null && steps.extract_tag_name.outputs.tag_name != 'refs/heads/main'
        id: create_release
        uses: actions/create-release@v1
        with:
          tag_name: ${{ steps.extract_tag_name.outputs.tag_name }}
          release_name: Release ${{ steps.extract_tag_name.outputs.tag_name }}
          body: Release ${{ steps.extract_tag_name.outputs.tag_name }} created automatically by GitHub Actions.
          token: ${{ secrets.ACTION_RELEASE }}
          draft: false
          prerelease: false
        env:
          GITHUB_TOKEN: ${{ secrets.ACTION_RELEASE }}

      - name: Upload Release Assets
        if: steps.extract_tag_name.outputs.tag_name != null && steps.extract_tag_name.outputs.tag_name != 'refs/heads/main'
        id: upload_asset
        uses: actions/upload-release-asset@v1
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: ./release.zip
          asset_name: release.zip
          asset_content_type: application/zip
        env:
          GITHUB_TOKEN: ${{ secrets.ACTION_RELEASE }}

已尝试但无效的方案 #

• GitHub LFS：尝试在工作流中把release.zip上传到LFS，推送失败，且不确定该方案是否可行
• 拆分zip文件：尝试拆分zip为多个部分，但actions/upload-release-asset@v1不支持多文件上传，且本地拆分后出现文件损坏问题
• 最大压缩：使用zip -mx9进行最高压缩，输出zip仍超3GB，问题未解决

可行解决方案 #

方案1：拆分文件并使用支持多文件上传的Action #

放弃旧版的actions/upload-release-asset@v1，改用支持批量上传的softprops/action-gh-release，同时用7z拆分大文件：

1. 修改Zip步骤，生成2GB分卷的压缩包：

7z a -r -v2G release.zip ./gui/

-v2G会将文件拆分为release.zip.001、release.zip.002等多个2GB以内的分卷文件。

2. 替换原有的Create Release和Upload Assets步骤：

- name: Create Release and Upload Assets
  if: steps.extract_tag_name.outputs.tag_name != null && steps.extract_tag_name.outputs.tag_name != 'refs/heads/main'
  uses: softprops/action-gh-release@v1
  with:
    tag_name: ${{ steps.extract_tag_name.outputs.tag_name }}
    name: Release ${{ steps.extract_tag_name.outputs.tag_name }}
    body: Release ${{ steps.extract_tag_name.outputs.tag_name }} created automatically by GitHub Actions.下载所有分卷后用7z解压即可。
    files: release.zip.*
  env:
    GITHUB_TOKEN: ${{ secrets.ACTION_RELEASE }}

用户下载所有分卷后，直接用7z打开任意一个分卷即可自动合并解压。

方案2：剥离大文件，让应用自动拉取 #

既然大文件已通过Git LFS存储，可以修改打包逻辑，不将其包含在release包中，改为应用首次启动时自动下载：

1. 修改prod.spec配置，排除该大文件，不打包进dist目录
2. 在应用启动代码中添加检查逻辑：如果本地不存在该大文件，通过GitHub API获取LFS文件的下载链接并拉取
3. 工作流中仅上传不含大文件的轻量化release包，用户安装后首次启动自动完成大文件的下载

方案3：使用GitHub Packages存储完整包 #

GitHub Packages支持单个文件最大10GB的存储，可以将完整的release.zip上传到Packages，然后在Release中添加下载引导：

在工作流中添加上传到Packages的步骤（以gh cli为例）：

- name: Upload to GitHub Packages
  if: steps.extract_tag_name.outputs.tag_name != null && steps.extract_tag_name.outputs.tag_name != 'refs/heads/main'
  run: |
    echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token
    gh package upload ${{ github.repository_owner }}/your-package-name release.zip --version ${{ steps.extract_tag_name.outputs.tag_name }}

之后在Release的描述中说明用户需要从GitHub Packages下载完整包。

内容的提问来源于stack exchange，提问作者user25541605