15、CMake vcpkg：vcpkg集成、CMAKE_TOOLCHAIN_FILE、查找vcpkg包

说到 C++ 的包管理，vcpkg 绝对是个绕不开的话题。我个人习惯把它叫做「微软家的包管家」。说实话，在 vcpkg 出现之前，C++ 项目的第三方库管理简直是一场噩梦——手动下载、编译、配置路径，稍有不慎就是一堆链接错误。

vcpkg 的出现，说白了就是帮你把「下载源码 → 编译 → 安装 → 配置 CMake 路径」这一整套流程自动化了。你只需要告诉它你要什么库，剩下的它全包了。

15.1 vcpkg 的两种集成模式

vcpkg 和 CMake 的集成，主要有两种方式。我在项目中两种都用过，各有各的适用场景。

15.1.1 全局集成（经典模式）

这是最常用的方式。你安装好 vcpkg 后，执行一次 vcpkg integrate install，vcpkg 就会在 CMake 的安装目录下注册一个 toolchain 文件。之后你所有 CMake 项目，只要在命令行里加上一句：

cmake -B build -DCMAKE_TOOLCHAIN_FILE=[vcpkg-root]/scripts/buildsystems/vcpkg.cmake

就能自动找到 vcpkg 安装的所有库。嗯，这里要注意，[vcpkg-root] 要替换成你实际的 vcpkg 安装路径。

我的习惯： 我会在环境变量里设置 VCPKG_ROOT，然后在 CMake 命令里写成 -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake。这样换机器时只需要改一个环境变量。

15.1.2 项目级集成（manifest 模式）

从 vcpkg 2020 版本开始，我强烈推荐使用 manifest 模式。你想想看，全局集成有个问题：不同项目可能需要同一个库的不同版本。manifest 模式完美解决了这个痛点。

你只需要在项目根目录放一个 vcpkg.json 文件：

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    "spdlog",
    "boost-asio"
  ]
}

然后在 CMakeLists.txt 里加上：

cmake_minimum_required(VERSION 3.14)
project(MyProject)

# 启用 manifest 模式
set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "")

# 或者通过命令行传入
# cmake -B build -DCMAKE_TOOLCHAIN_FILE=...

find_package(fmt CONFIG REQUIRED)
find_package(spdlog CONFIG REQUIRED)
find_package(Boost COMPONENTS asio REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE fmt::fmt spdlog::spdlog Boost::asio)
我曾经踩过的坑： 有一次我忘了在 vcpkg.json 里声明依赖，直接在 CMakeLists.txt 里 find_package。结果 vcpkg 根本没下载那个库，编译报错说找不到包。记住：manifest 模式下，vcpkg 只安装 vcpkg.json 里列出的库。

15.2 CMAKE_TOOLCHAIN_FILE 的作用

这个变量是 CMake 和 vcpkg 集成的核心。说白了，它告诉 CMake：「嘿，别用你默认的查找路径了，去 vcpkg 的安装目录里找库。」

vcpkg 提供的 toolchain 文件会做以下几件事：

  • 设置 CMAKE_PREFIX_PATH 指向 vcpkg 的 installed 目录
  • 设置 CMAKE_FIND_ROOT_PATH 确保查找路径不出界
  • 注入 vcpkg 的 triplet 信息（比如 x64-windows、x64-linux）
  • 处理库的依赖关系（比如你装了一个库，它依赖的其他库也会被自动找到）

我个人习惯在项目的 CMakePresets.json 里配置好 toolchain 路径，这样团队成员拉下代码后直接 cmake --preset=default 就能用，不用每个人手动敲参数。

{
  "version": 3,
  "configurePresets": [
    {
      "name": "default",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

15.3 查找 vcpkg 包的完整流程

当你在 CMake 里写 find_package(fmt CONFIG) 时，背后发生了什么？我画了一张图帮你理解：

vcpkg 包查找流程 find_package(fmt CONFIG) CMAKE_TOOLCHAIN_FILE 介入 设置 CMAKE_PREFIX_PATH → vcpkg/installed/x64-windows 找到 fmtConfig.cmake → 导入目标 整个过程对开发者透明，你只需要写 find_package 一行代码

流程其实很清晰：

  1. CMake 执行 find_package 命令
  2. toolchain 文件被加载，修改了 CMake 的查找策略
  3. CMake 在 vcpkg 的安装目录下搜索对应的 *Config.cmake 文件
  4. 找到后导入库的目标（target），你就可以用 target_link_libraries 链接了

15.4 常见问题与避坑指南

问题1：找不到包，提示 "Could not find a package configuration file"

我曾经遇到过这个问题，排查后发现是 triplet 不匹配。比如你安装的是 x64-windows，但 CMake 默认找的是 x86-windows。解决办法：

cmake -B build -DCMAKE_TOOLCHAIN_FILE=... -DVCPKG_TARGET_TRIPLET=x64-windows

问题2：vcpkg 安装的库版本不对

manifest 模式下，你可以在 vcpkg.json 里指定版本约束：

{
  "dependencies": [
    {
      "name": "fmt",
      "version>=": "10.0.0"
    }
  ]
}

问题3：CMake 缓存导致路径混乱

如果你切换了 vcpkg 的 triplet 或者更新了库，记得清空 build 目录重新配置。我习惯在 CMakePresets.json 里把 build 目录设为 build/${presetName}，这样不同配置互不干扰。

15.5 实战：一个完整的 vcpkg + CMake 项目

说了这么多，我们来个完整的例子。假设我们要写一个日志工具，用 spdlog 和 fmt：

项目结构：

my-logger/
├── CMakeLists.txt
├── vcpkg.json
├── src/
│   └── main.cpp
└── CMakePresets.json

vcpkg.json：

{
  "name": "my-logger",
  "version": "1.0.0",
  "dependencies": [
    "spdlog",
    "fmt"
  ]
}

CMakeLists.txt：

cmake_minimum_required(VERSION 3.14)
project(MyLogger VERSION 1.0.0 LANGUAGES CXX)

# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 查找 vcpkg 包
find_package(fmt CONFIG REQUIRED)
find_package(spdlog CONFIG REQUIRED)

# 可执行文件
add_executable(my_logger src/main.cpp)

# 链接库
target_link_libraries(my_logger PRIVATE
    fmt::fmt
    spdlog::spdlog
)

src/main.cpp：

#include <spdlog/spdlog.h>
#include <fmt/core.h>

int main() {
    spdlog::info("欢迎使用 vcpkg + CMake 集成示例");
    spdlog::warn("这是一个警告信息");
    
    std::string name = "CMake";
    fmt::print("Hello, {}!\n", name);
    
    return 0;
}

CMakePresets.json：

{
  "version": 3,
  "configurePresets": [
    {
      "name": "default",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/default",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

配置和编译：

# 配置
cmake --preset=default

# 编译
cmake --build build/default

# 运行
./build/default/my_logger

我的建议： 如果你团队里有人不用 vcpkg，或者想用系统安装的库，可以在 CMakeLists.txt 里加个 fallback 逻辑：

if(NOT DEFINED CMAKE_TOOLCHAIN_FILE)
    # 尝试找系统安装的库
    find_package(fmt CONFIG QUIET)
    find_package(spdlog CONFIG QUIET)
endif()

这样既支持 vcpkg，也兼容手动安装的场景。

好了，关于 vcpkg 和 CMake 的集成，核心就是这些。说白了就是三件事：配好 toolchain 文件、写对 vcpkg.json、用 find_package 查找。把这三点搞明白，你就能优雅地管理 C++ 项目的第三方依赖了。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →