在 GitHub Actions 上通过基于 Docker 的 CMake 构建环境简化 Qt6 CI

Source: Dev.to

Problem Statement

Qt6 功能强大，但在 GitHub Actions 上为 Qt6 项目搭建可靠的 CI 流水线却出乎意料地痛苦。

• 复杂的依赖需求
• 根据 Qt 版本不同而有所差异的设置步骤
• CMake + Ninja 环境不一致
• 本地环境与 CI 环境之间的差异
• 使用 aqtinstall 时的平台特定问题

Qt6 CI 最大的挑战是环境不一致：

• 依赖在 GitHub‑hosted runner 之间不同
• Qt6 在不同操作系统和版本下的表现略有差异
• aqtinstall 在不同平台上可能产生不同的结果

试图在 GitHub Action 中直接支持所有这些情况会很快变得混乱。

Solution Overview

基于 Docker 的 Qt6 CMake CI Action 为在 GitHub Actions 上构建 Qt6 项目提供了完全可复现的环境。

• 所有 runner（Ubuntu、Windows、macOS）使用相同的基于 Ubuntu 的环境
• 零依赖差异
• 完全可复现的构建
• 再也没有平台特定的惊喜

该 Action 自动完成构建 Qt6 项目所需的一切：

1. 使用 aqtinstall 安装 Qt6
2. 设置 CMake + Ninja
3. 在 Docker 容器内构建项目
4. 兼容所有 GitHub‑hosted runner
5. 自动处理 Qt 版本差异

Features

• 基于 Docker 的稳定性 – 构建始终在 Linux Docker 容器中运行。
• CMake + Ninja 已预装。
• 自动安装核心 Qt6 模块（Core、GUI、Widgets、QML、Quick）。
• 可指定可选的附加模块（例如 qtimageformats、qtshadertools）。
• 支持 Ubuntu、Windows 和 macOS GitHub‑hosted runner。
• GUI 测试支持（Xvfb / noVNC）。
• 构建缓存，加速 CI。
• Qt Installer Framework 自动化。

Usage

Minimal workflow

name: Build Qt6 Project
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Qt6 and build
        uses: acc-vcc/qt6-cmake-ci-action@v1
        with:
          qt-version: "6.6.1"
          # modules: "qtimageformats qtshadertools"  # Only needed for add‑on modules

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build
          path: build/

Action inputs

Example of specifying additional modules

with:
  qt-version: "6.6.1"
  modules: "qtimageformats qtshadertools"

Benefits

• 完全可复现的环境 – 每个 runner 上的构建完全相同。
• 相同的构建行为 在 Ubuntu、Windows 和 macOS runner 之间保持一致。
• Qt 版本设置 自动完成。
• 基于 Docker 的稳定性 消除平台特定的惊喜。

Getting the Action

🔗 Qt6 CMake CI Action on GitHub Marketplace

Future Plans

• 持续改进 Action，让 Qt 开发对所有人更顺畅。
• 增加更多 GUI 测试功能。
• 强化构建缓存策略。