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

1.背景

环境：windows10 + VS2022

项目：cmake项目

包管理器：vcpkg

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

#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中添加：

{ "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 工具链文件，填入路径。

{ "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 中设置

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

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变量值的设置，

{ "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" } ] }

同时配合上述方法三：

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