如何在GitHub Actions中用MSBuild与windeployqt构建Qt C++项目

完整YAML构建脚本 #

name: Windows Qt Build

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: windows-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        submodules: recursive # 若第三方库以子模块形式引入，开启此项

    - name: Install Qt
      uses: jurplel/install-qt-action@v4
      with:
        version: '6.5.0' # 替换为你的项目依赖的Qt版本
        host: 'windows'
        target: 'desktop'
        arch: 'win64_msvc2019_64' # 匹配MSVC版本，VS2022对应win64_msvc2022_64
        modules: 'qtbase qtwidgets' # 替换为项目实际依赖的Qt模块
        setup-python: false

    - name: Install vcpkg and dependencies
      run: |
        git clone https://github.com/microsoft/vcpkg.git
        .\vcpkg\bootstrap-vcpkg.bat
        .\vcpkg\vcpkg install curl:x64-windows nlohmann-json:x64-windows
        .\vcpkg\vcpkg integrate install
      shell: pwsh

    - name: Build with MSBuild
      run: |
        msbuild your_project.vcxproj `
          /p:Configuration=Release `
          /p:Platform=x64 `
          /p:UseVcpkg=true `
          /m # 并行构建加速
      shell: pwsh
      working-directory: ./path/to/project # 替换为你的项目文件所在目录

    - name: Deploy Qt dependencies
      run: |
        windeployqt .\x64\Release\your_app.exe `
          --release `
          --x64 `
          --no-compiler-runtime `
          --no-angle `
          --no-opengl-sw
      shell: pwsh
      working-directory: ./path/to/project

    - name: Upload build artifact
      uses: actions/upload-artifact@v4
      with:
        name: windows-qt-app
        path: ./path/to/project/x64/Release/

关键配置说明 #

1. Qt环境配置 #

使用jurplel/install-qt-action自动安装指定版本的Qt，并配置QTDIR、Qt6_DIR等环境变量，避免手动查找Qt路径出错，确保MSBuild和windeployqt能直接识别Qt位置。

2. 第三方库处理 #

• cURL：通过vcpkg安装后，vcpkg integrate install会将库和头文件路径自动集成到MSBuild默认配置，无需手动设置INCLUDE或LIB环境变量。
• nlohmann JSON：vcpkg安装后会自动加入MSBuild包含路径；若使用源码，需在MSBuild参数中通过/p:AdditionalIncludeDirectories=".\external\nlohmann_json;$(AdditionalIncludeDirectories)"指定源码目录。

3. MSBuild构建参数 #

• 必须明确指定Configuration=Release和Platform=x64，避免默认配置与项目不匹配。
• /p:UseVcpkg=true确保MSBuild加载vcpkg集成配置，正确识别第三方库。
• 若项目不在仓库根目录，通过working-directory指定项目文件所在路径。

4. Windeployqt部署 #

• 指定exe完整路径，添加--release和--x64匹配构建配置和平台。
• --no-compiler-runtime避免重复打包VC运行库（需要打包则移除该参数）。
• 根据项目需求调整其他参数（如--no-angle禁用ANGLE渲染）。

常见问题修复 #

• 构建无输出无错误：检查MSBuild是否指定了正确的项目路径、配置和平台；确保步骤指定了shell: pwsh或shell: cmd，避免命令未执行。
• 头文件路径无法识别：确认第三方库包含路径已通过vcpkg集成或AdditionalIncludeDirectories正确设置；Qt头文件路径由install-qt-action自动配置，无需手动添加。
• 第三方库链接失败：确保vcpkg安装的库平台（x64/x86）与MSBuild指定平台一致；使用源码库时，需确保库文件已编译并在MSBuild中指定AdditionalLibraryDirectories。

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