Github Actions中PyInstaller构建的.exe文件无法运行问题排查

问题描述 #

我尝试通过Github Actions自动构建Python代码仓库的Windows .exe和Linux可执行文件。本地使用相同PyInstaller命令生成的Windows .exe约8MB，可正常运行；但Github Actions生成的.exe仅6.8MB且无法启动。同时我想了解，Linux版本是否需要在构建时添加chmod +x权限，还是由用户自行设置？我的目标是生成两个可在对应操作系统正常运行的可执行文件。以下是使用的YAML配置文件：

name: Package offlineEditor.exe
on:
  workflow_dispatch:
  push:
    branches: ["master", "main"]

jobs:
  build:
    strategy:
      matrix:
        os: ['windows-latest', 'ubuntu-latest']
        python-version: ["3.10"]
    runs-on: ${{ matrix.os }}
        
    steps:
      - uses: actions/checkout@v4
        name: Checkout

      - uses: actions/setup-python@v5
        name: Setup Python
        with:
          python-version: ${{ matrix['python-version'] }}

      - name: Refresh data folder from source
        run: |
          rm -r compiled/editor/data
          cp -r src/data/ compiled/editor/data/

      - name: Build Executables (Windows)
        if: ${{ matrix.os == 'windows-latest' }}
        run: |
          Remove-Item -Path "compiled/editor/offlineEditor-windows.exe" -Force -ErrorAction SilentlyContinue
          pip install pyinstaller
          pyinstaller --distpath compiled/editor --workpath /tmp/win/ --name offlineEditor-windows.exe --clean --icon="src/data/icon.ico" -F src/main.py

      - name: Upload Artifacts (Windows)
        if: ${{ matrix.os == 'windows-latest' }}
        uses: actions/upload-artifact@v4
        with:
          name: offlineEditor-artifact-windows
          path: compiled/editor/offlineEditor-windows.exe

      - name: Build Executables (Linux)
        if: ${{ matrix.os == 'ubuntu-latest' }}
        run: |
          rm -rf compiled/editor/offlineEditor-linux.sh
          pip install pyinstaller
          pyinstaller --distpath compiled/editor --workpath /tmp/linux/ --name offlineEditor-linux.sh --clean --icon="src/data/icon.ico" -F src/main.py

      - name: Upload Artifacts (Linux)
        if: ${{ matrix.os == 'ubuntu-latest' }}
        uses: actions/upload-artifact@v4
        with:
          name: offlineEditor-artifact-linux
          path: compiled/editor/offlineEditor-linux.sh

      - name: Commit Artifacts
        if: always()  # Stellen sicher, dass dieser Schritt immer ausgeführt wird
        run: |
          git config --global user.email "github-actions@github.com"
          git config --global user.name "GitHub Actions"
          git pull origin main  # Aktualisieren Sie zuerst lokale Änderungen
          git add .
          git commit -m "Automated build"
          git push origin main

Windows可执行文件体积过小且无法启动的解决办法 #

• 安装完整项目依赖：GitHub Actions的Windows runner是纯净环境，本地可能有额外依赖或缓存组件。构建前先执行pip install -r requirements.txt（确保项目有requirements.txt文件），再安装PyInstaller，避免依赖缺失导致打包不完整。
• 固定PyInstaller版本：本地与Actions环境的PyInstaller版本差异可能导致打包逻辑不同。指定固定版本安装，比如pip install pyinstaller==5.13.2，保证打包行为一致。
• 正确包含资源文件：PyInstaller打包时可能未自动包含src/data下的资源，导致启动失败。修改PyInstaller命令，添加--add-data "src/data/*;data/"（Windows用分号分隔路径），确保资源被打包进可执行文件。
• 添加调试步骤：在Windows构建步骤中加入测试启动命令，比如compiled/editor/offlineEditor-windows.exe，查看控制台报错信息，精准定位缺失组件或路径问题。

Linux可执行文件权限设置建议 #

• 构建时直接添加执行权限：PyInstaller生成的Linux可执行文件默认带执行权限，但为了避免意外，建议在构建完成后执行chmod +x compiled/editor/offlineEditor-linux.sh，用户下载后可直接运行。
• 优化Linux构建脚本：修改YAML中的Linux构建步骤，更新run脚本如下：

  rm -rf compiled/editor/offlineEditor-linux
  pip install pyinstaller
  pyinstaller --distpath compiled/editor --workpath /tmp/linux/ --name offlineEditor-linux --clean --icon="src/data/icon.ico" -F src/main.py
  chmod +x compiled/editor/offlineEditor-linux
  

  同时去掉.sh后缀，更符合Linux可执行文件的命名惯例。

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