如何在GitHub Actions矩阵配置中添加PyQt5支持Qt5Agg后端

报错原因 #

之前出现的ImportError: cannot import name 'appdirs'报错，是因为全局配置了PYTHONPATH: ":/usr/lib/python3/dist-packages"，将Ubuntu系统自带Python的第三方包路径优先级提前，和actions/setup-python部署的独立版本Python环境依赖版本冲突，导致pip加载了系统自带的旧版组件，与当前运行的Python版本不兼容。

跨系统兼容矩阵配置 #

直接通过pip安装PyQt5即可，无需安装系统级PyQt包、无需全局修改PYTHONPATH，天然支持matrix.python-version多版本配置与matrix.os多操作系统配置，参考配置如下：

name: PyQt5 CI
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  workflow_dispatch:

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        # PyQt5官方预编译包支持Python 3.7~3.12，可按需调整版本范围
        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]

    steps:
      - name: Checkout 代码
        uses: actions/checkout@v4

      - name: 配置Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'

      - name: 安装依赖
        run: |
          python -m pip install --upgrade pip
          pip install pyqt5 matplotlib pytest pytest-cov

      - name: 验证Qt5Agg后端可用性
        run: |
          cat > test_qt5.py <<EOF
          import matplotlib
          matplotlib.use('Qt5Agg')
          from PyQt5 import QtCore, QtWidgets
          print("PyQt5 Qt5Agg后端加载成功")
          EOF
          python test_qt5.py

      - name: 运行测试
        run: pytest

配置注意事项 #

• 不要全局设置PYTHONPATH环境变量，避免系统包和独立Python环境的依赖出现冲突
• 无需通过apt等系统包管理器安装PyQt5，pip源提供的PyQt5为预编译wheel包，自动适配Ubuntu、Windows、macOS三类运行环境，可直接匹配矩阵配置的对应Python版本
• 无需强制限制Python版本为3.6及以下，3.7及以上版本均可正常运行，也无需额外安装PyQt4相关依赖，仅安装PyQt5即可满足Qt5Agg后端运行要求
• 若特殊场景必须使用Ubuntu系统源自带的PyQt5包，仅在运行测试脚本的单一步骤临时指定PYTHONPATH即可，不要将该环境变量应用到安装依赖等其他步骤，避免触发pip导入错误，示例写法：

  - name: 基于系统PyQt5运行测试
    run: python test_qt5.py
    env:
      PYTHONPATH: "/usr/lib/python3/dist-packages"
  

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