基于 vcpkg 与 LLVM-MinGW 的 Qt6 静态链接开发方案

环境准备

在执行下面的操作之前，请确保已经安装下列开发必要的工具。建议统一放在 ~/tools 目录下，并将其加入系统环境变量：

CMake：https://cmake.org/download/
Ninja：https://github.com/ninja-build/ninja/releases
Git：https://git-scm.com
LLVM-MinGW(ucrt)：https://github.com/mstorsjo/llvm-mingw/releases

安装与配置 vcpkg

打开命令行（CMD），建议在当前用户的 tools 文件夹下执行以下命令来获取并安装 vcpkg：

cmd 复制代码

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
bootstrap-vcpkg.bat

提示： 新版的 vcpkg 不再本地编译自己，而是直接下载官方发布版到本目录。您会看到类似如下的输出： Downloading [https://github.com/microsoft/vcpkg-tool/releases/download/2026-04-08/vcpkg.exe](https://github.com/microsoft/vcpkg-tool/releases/download/2026-04-08/vcpkg.exe) -> C:\Users\touken\tools\vcpkg\vcpkg.exe

在 Windows 的"编辑环境变量"图形界面中：

先新建 VCPKG_ROOT ：
在"用户变量"里点击"新建"，变量名填 VCPKG_ROOT，变量值填 C:\Users\touken\tools\vcpkg。
在 PATH 里直接引用它 ：
找到并双击打开用户变量里的 Path，点击"新建"，直接填入 %VCPKG_ROOT%。

(注：设置完环境变量后，建议重新打开您的命令行终端或 IDE 以使其生效。)

初始化项目

首先，在您的项目根目录下使用以下命令创建 vcpkg.json 和 vcpkg-configuration.json：

复制代码

vcpkg new --application

通常我们可以使用 vcpkg add port <包名> 来添加包，但由于我们明确只需要 Qt 的 GUI 相关包，可以直接手动编辑vcpkg.json配置。

json 复制代码

{
  "dependencies": [
    {
      "name": "qtbase",
      "default-features": false,
      "features": [
        "gui",
        "widgets"
      ]
    }
  ]
}

接下来，创建 CMake 配置CMakeLists.txt文件，用于组织和编译项目。

cmake 复制代码

cmake_minimum_required(VERSION 3.21)
project(sandbox LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_AUTOMOC ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets)

add_executable(sandbox WIN32 src/main.cpp)

target_link_libraries(sandbox PRIVATE Qt6::Widgets)

在src/main.cpp编写一个基础的 Qt GUI 示例代码。

C++ 复制代码

#include <QApplication>
#include <QPushButton>

int main(int argc, char *argv[]) {
  QApplication app(argc, argv);

  QPushButton button("Hello Qt6 + vcpkg");
  button.resize(320, 120);
  button.show();

  return app.exec();
}

现代 CMake 官方推荐将工具链、Triplet、编译器等底层配置全部集中写进CMakePresets.json预设文件中。

json 复制代码

{
    "version": 6,
    "configurePresets": [
        {
            "name": "base",
            "hidden": true,
            "generator": "Ninja",
            "cacheVariables": {
                "CMAKE_C_COMPILER": "clang",
                "CMAKE_CXX_COMPILER": "clang++",
                "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
                "VCPKG_TARGET_TRIPLET": "x64-mingw-static"
            }
        },
        {
            "name": "debug",
            "displayName": "LLVM MinGW + vcpkg (Debug)",
            "inherits": "base",
            "binaryDir": "${sourceDir}/build-debug",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Debug",
                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
            }
        },
        {
            "name": "release",
            "displayName": "LLVM MinGW + vcpkg (Release)",
            "inherits": "base",
            "binaryDir": "${sourceDir}/build-release",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Release",
                "CMAKE_CXX_FLAGS": "-static-libstdc++ -static-libgcc",
                "CMAKE_EXE_LINKER_FLAGS": "-static -static-libstdc++ -static-libgcc"
            }
        }
    ],
    "buildPresets": [
        {
            "name": "debug",
            "configurePreset": "debug"
        },
        {
            "name": "release",
            "configurePreset": "release"
        }
    ]
}

编译项目

所有配置准备就绪后，在项目根目录下依次执行以下命令，通过预设好的 release 配置进行项目构建：

cmd 复制代码

# 配置项目
cmake --preset release

# 编译项目
cmake --build --preset release

代码提示与格式化

为了在 VS Code 中获得丝滑的代码跳转和智能提示（IntelliSense），推荐使用 clangd 插件代替微软官方的 C/C++ 插件。

由于我们在 CMakePresets.json 中开启了 CMAKE_EXPORT_COMPILE_COMMANDS，CMake 会在 build-debug目录下生成 compile_commands.json。我们需要告知 clangd 读取该文件以识别 Qt 的头文件路径。

在项目根目录下创建 .vscode/settings.json，配置如下：

json 复制代码

{
    // 禁用微软官方 C/C++ 插件的 IntelliSense，防止与 clangd 冲突
    "C_Cpp.intelliSenseEngine": "disabled",

    // 配置 clangd 启动参数
    "clangd.arguments": [
        // 指向编译数据库所在目录
        "--compile-commands-dir=${workspaceFolder}/build-debug",
        // 后台自动分析文件并建立索引（推荐开启）
        "--background-index",
        // 启用 clang-tidy 静态代码检查，实时发现潜在错误
        "--clang-tidy",
        // 智能头文件插入策略：按需自动补充 #include
        "--header-insertion=iwyu",
        // 允许 clangd 使用 4 个并行工作线程（根据你的 CPU 核心数调整）
        "-j=4"
    ]
}

clangd 内置了强大的格式化引擎。通过在项目根目录下放置 .clang-format 文件，可以确保团队开发环境下的代码风格高度统一。

以下是一份适配现代 C++ 开发习惯的推荐配置（4 空格缩进，不强制列宽限制）：

yaml 复制代码

Language: Cpp
# 基础风格
BasedOnStyle: Google
IndentWidth: 4
TabWidth: 4
UseTab: Never
ColumnLimit: 0 # 不限制单行长度，由开发者自行判断换行

# 访问修饰符（public/private）缩进
AccessModifierOffset: -4

# 括号与空格
Standard: Auto
Cpp11BracedListStyle: true
SpacesInContainerLiterals: true
SpaceBeforeParens: ControlStatements
SpaceAfterTemplateKeyword: true

# 指针对齐方式（靠右：int *ptr）
PointerAlignment: Right
DerivePointerAlignment: false

# 代码块换行策略
BreakBeforeBraces: Custom
BraceWrapping:
  AfterClass: false
  AfterControlStatement: false
  AfterEnum: false
  AfterFunction: false
  AfterNamespace: false
  AfterStruct: false
  BeforeElse: false
  IndentBraces: false

# 允许短代码单行显示
AllowShortBlocksOnASingleLine: true
AllowShortIfStatementsOnASingleLine: true
AllowShortFunctionsOnASingleLine: None

# 模板与命名空间
AlwaysBreakTemplateDeclarations: true
CompactNamespaces: true
NamespaceIndentation: None

# 包含文件排序
SortIncludes: false

提示：配置完成后，建议在 VS Code 中执行 Clangd: Restart language server 确保配置立即生效。现在，你可以享受毫秒级的代码补全和 Alt + Shift + F 一键美化代码的快感了。

总结

本方案通过 vcpkg 自动化管理 Qt6 复杂依赖，结合 LLVM-MinGW 实现 Windows 下的现代化编译。通过 CMake Presets 确保了配置的可移植性，并通过 clangd 提供了丝滑的编码体验。最终实现的静态链接发布方式，极大地简化了 Qt 应用的分发成本。