使用GitHub Actions+PyInstaller构建Kivy应用遇OpenGL版本问题求助

在GitHub Actions的Windows无头Runner上用PyInstaller打包Kivy应用时，会因为Runner默认的OpenGL版本仅1.1（低于Kivy要求的2.0），且无法启动SDL2图形环境，导致Kivy初始化失败、构建停滞。以下是具体解决方法：

核心思路 #

通过设置Kivy的环境变量，强制使用mock OpenGL后端，让Kivy在打包过程中跳过真实的图形上下文初始化，避免触发版本检测错误。

修改工作流配置 #

更新你的.github/workflows/build-win.yml，在PyInstaller构建步骤前添加Kivy环境变量：

name: Build Kivy App

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: windows-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install kivy pyinstaller

    - name: Build with PyInstaller
      env:
        # 强制使用mock OpenGL后端，跳过图形初始化
        KIVY_GL_BACKEND: mock
        # 禁用Kivy的视频模块初始化，避免额外图形操作
        KIVY_VIDEO: null
      run: |
        pyinstaller --onefile main.py

    - name: Upload artifact
      uses: actions/upload-artifact@v4
      with:
        name: kivy-app
        path: dist/main.exe

原理说明 #

• KIVY_GL_BACKEND=mock：让Kivy使用模拟的OpenGL后端，不会尝试加载真实的图形驱动，直接绕过版本检测环节。
• KIVY_VIDEO=null：禁用视频模块的初始化逻辑，进一步减少打包过程中不必要的图形相关操作。

修改后，PyInstaller打包时Kivy不会触发OpenGL检测，能在GitHub Actions的无头环境顺利完成构建，生成的.exe文件在具备符合要求OpenGL环境的正常Windows系统中可正常运行。

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