记录一次cmake无法正确使用vcpkg的问题

1.背景

环境：windows10 + VS2022

项目：cmake项目

包管理器：vcpkg

此前通过VS2022使用cmake项目都正常，包括设置cmake工具链文件为vcpkg，但是昨天使用VS2022配置cmake报错，find_package freetype库时找不到

javascript 复制代码

#freetype
find_package(Freetype REQUIRED)
target_link_libraries(main PRIVATE Freetype::Freetype) # since CMake 3.10

已经通过vcpkg在本地安装了freetype，并且设置了环境变量：VCPKG_ROOT，

然后调试cmakelists.txt，发现CMAKE_TOOLCHAIN_FILE变量值是VS2022安装目录下子目录中的vcpkg.cmake

"D:\Program Files\Microsoft Visual Studio\2022\Professional\VC\vcpkg\scripts\buildsystems\vcpkg.cmake"，

这就不对了，我本地自己的vcpkg安装位置是其它位置，包括通过vcpkg安装的包。

2.方法论

首先有几种方法可以设置cmake工具链文件：

方法一：使用 Visual Studio 的 CMake 配置文件

Visual Studio 2019 16.10+ 推荐使用 CMakePresets.json 来管理默认配置。

打开项目根目录，创建或编辑 CMakePresets.json。
在 configurePresets 中添加：

javascript 复制代码

{
  "version": 3,
  "configurePresets": [
    {
      "name": "x64-debug",
      "hidden": false,
      "generator": "Ninja",
      "description": "Debug build with vcpkg toolchain",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "D:/vcpkg/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

方法二：使用 CMakeSettings.json

如果项目还在用旧的 CMakeSettings.json：

在 Visual Studio 中选择 配置 → 管理配置。
在编辑器中找到 CMake 工具链文件，填入路径。

javascript 复制代码

{
  "configurations": [{
    "name": "x64-Debug",
    "generator": "Visual Studio 15 2017",
    "configurationType" : "Debug",
    "buildRoot":  "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
    "cmakeCommandArgs": "",
    "buildCommandArgs": "-m -v:minimal",
    "variables": [{
      "name": "CMAKE_TOOLCHAIN_FILE",
      "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
    }]
  }]
}

注意： 新版VS推荐使用CMakePresets.json来管理默认设置， 可以在VS的工具》选项中查看和配置：

方法三：在 CMakeLists.txt 中设置

如果你想在项目脚本中直接指定：

javascript 复制代码

cmake_minimum_required(VERSION 3.20)

# 必须在 project() 之前设置
set(CMAKE_TOOLCHAIN_FILE "D:/vcpkg/scripts/buildsystems/vcpkg.cmake")

project(demo)

注意

上述方法优先级 ：命令行参数 -DCMAKE_TOOLCHAIN_FILE=... 的优先级最高，会覆盖配置文件。
跨平台 ：不同平台可能需要不同的工具链文件，可以在 CMakePresets.json 中为每个平台定义不同的 preset。
兼容性 ：Visual Studio 旧版本可能不支持 CMakePresets.json，需使用 CMakeSettings.json。

3.排查思路

1）作者使用的是cmakepresets.json，在其中设置了CMAKE_TOOLCHAIN_FILE变量，无奈还是报错，

然后在VS2022中查看配置cmake时的输出信息，

命令行: "C:\WINDOWS\system32\cmd.exe" /c "%SYSTEMROOT%\System32\chcp.com 65001 >NUL && "D:\PROGRAM FILES\MICROSOFT VISUAL STUDIO\2022\PROFESSIONAL\COMMON7\IDE\COMMONEXTENSIONS\MICROSOFT\CMAKE\CMake\bin\cmake.exe" -G "Ninja" -DCMAKE_TOOLCHAIN_FILE:STRING="D:\Program Files\Microsoft Visual Studio\2022\Professional\VC\vcpkg/scripts/buildsystems/vcpkg.cmake" -DCMAKE_BUILD_TYPE:STRING="Debug" -DCMAKE_INSTALL_PREFIX:STRING="D:/git/3rdParty/cglib" -DCMAKE_MAKE_PROGRAM="D:\PROGRAM FILES\MICROSOFT VISUAL STUDIO\2022\PROFESSIONAL\COMMON7\IDE\COMMONEXTENSIONS\MICROSOFT\CMAKE\Ninja\ninja.exe" "D:\git\cglib" 2>&1"

显然当前环境的环境变量：VCPKG_ROOT 已经覆盖了我本地设置的变量值，并且VS启动cmake时以-DCMAKE_TOOLCHAIN_FILE方式传递了该值（优先级最高），继续排查~

同时CmakeCache.txt中也是：

2）作者使用上述方法三设置，不管用，因为VS启动cmake时以-DCMAKE_TOOLCHAIN_FILE方式传递了该值（优先级最高），继续排查~

3）作者在VS2022的工具》选项中的vcpkg程序包管理器中设置，依然没有解决问题；

4.解决问题

好吧，虽然按论及来说咱没有使用cmakesetting.json，但还是配置下吧，注意cmakeToolchain变量值的设置，

javascript 复制代码

{
  "configurations": [
    {
      "name": "x64-Release",
      "generator": "Ninja",
      "configurationType": "Release",
      "inheritEnvironments": [ "msvc_x64_x64" ],
      "buildRoot": "${projectDir}\\out\\build\\${name}",
      "installRoot": "${projectDir}\\out\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": "",
      "cmakeToolchain": "D:/git/vcpkg/scripts/buildsystems/vcpkg.cmake"
    }
  ]
}

同时配合上述方法三：

javascript 复制代码

cmake_minimum_required(VERSION 3.20)

# 必须在 project() 之前设置
set(CMAKE_TOOLCHAIN_FILE "D:/vcpkg/scripts/buildsystems/vcpkg.cmake")

project(demo)

问题解决......

来看CmakeCache.txt

按理来说我的VS设置中不会使用CmakeSetting.json了，但是问题就是解决了......

当然还有一种逻辑更靠谱的办法是卸载VS自带的vcpkg，这样就不会与自己配置的起冲突了，

VS2022中工具》获取工具和功能：

5.参考

1）Installing and Using Packages Example: SQLite

https://github.com/MicrosoftDocs/vcpkg-docs/blob/main/vcpkg/examples/installing-and-using-packages.md#cmake

2）自定义 CMake 生成设置

https://learn.microsoft.com/zh-cn/cpp/build/customize-cmake-settings?view=msvc-170

3）CMAKE_TOOLCHAIN_FILE

https://cmake.com.cn/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html

4）deepseek和微软Copilot