vcpkg manifest mode是vcpkg自2022年起主推的声明式依赖管理方式，以项目根目录的vcpkg.json替代手动install命令，实现per-project、per-triplet隔离；传统方式将包装入全局vcpkg/installed/路径，易引发ABI冲突。
什么是 vcpkg manifest mode，它和传统方式有什么根本区别？
vcpkg manifest mode 是 vcpkg 从 2022 年起主推的声明式依赖管理方式，核心是用 vcpkg.json 文件替代手动调用 vcpkg install。它不是“额外功能”，而是让 vcpkg 真正成为项目级依赖工具的关键切换——依赖绑定到项目目录，而非全局或用户环境。
传统方式（vcpkg install zlib x64-windows）会把包装进 vcpkg/installed/ 全局路径，多个项目共享同一份二进制，极易引发 ABI 冲突或版本漂移；manifest mode 则为每个项目生成独立的 vcpkg_installed/ 目录，并通过 CMake 工具链自动注入依赖，实现 per-project、per-triplet 隔离。
如何初始化并正确编写 vcpkg.json？
vcpkg.json 必须放在项目根目录（即 CMakeLists.txt 同级），且必须包含 name、version 和 dependencies 字段。vcpkg 不接受空依赖或缺失字段，否则 vcpkg install 会直接报错退出。
-
name必须是合法标识符（仅含字母、数字、下划线，不能以数字开头），且与项目实际名称一致——CMake 导入时会校验该名称是否匹配find_package()调用 -
dependencies中的包名必须是 vcpkg registry 中存在的端口名（如fmt、boost-system），不支持别名或自定义别名 - 若需指定 triplet（如
x64-windows-static-md），**不能写在vcpkg.json里**，而应在 CMake 配置阶段传入，例如：-DVCPKG_TARGET_TRIPLET=x64-windows-static-md
{
"name": "myapp",
"version": "0.1.0",
"dependencies": [
"fmt",
{
"name": "boost-system",
"features": ["regex"]
}
]
}
CMakeLists.txt 怎么对接 manifest mode？
关键不是手动 find_package()，而是启用 vcpkg 的自动集成机制：必须通过 vcpkg 提供的 CMake 工具链文件触发依赖解析。否则 vcpkg.json 形同虚设。
立即学习“C++免费学习笔记（深入）”；
- 必须在
cmake命令中显式指定-DCMAKE_TOOLCHAIN_FILE指向 vcpkg 的 toolchain（如/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake） - 无需在 CMakeLists.txt 中调用
vcpkg_configure_cmake或include(vcpkg)—— 这些是旧模式遗留，manifest mode 下会干扰自动发现 -
find_package(fmt CONFIG REQUIRED)可直接使用，vcpkg 会在 configure 阶段自动注册fmtConfig.cmake到CMAKE_PREFIX_PATH - 若项目含子目录（如
src/、test/），确保所有add_executable()/add_library()调用前已执行find_package()，否则链接会失败
常见失败场景和排查要点
manifest mode 下错误信息往往藏在 CMake configure 日志末尾，而不是 vcpkg 命令输出里。最常踩的坑不是语法错，而是路径和生命周期错位。
- 运行
vcpkg install后没看到vcpkg_installed/目录？检查当前工作目录是否为vcpkg.json所在目录，且该目录下有 CMakeLists.txt —— vcpkg 会扫描父目录找 CMakeLists.txt，但不会跨 Git 工作区边界 - CMake 报错 “Could not find fmt”？确认
find_package(fmt CONFIG REQUIRED)的CONFIG关键字存在（否则 fallback 到 module 模式，找不到Findfmt.cmake） - 链接时报 undefined symbol？大概率是 triplet 不匹配：CMake 默认用
x64-windows，但vcpkg.json依赖的包可能只构建了x64-windows-static—— 此时必须统一指定-DVCPKG_TARGET_TRIPLET - CI 构建失败提示 “no suitable port found”？检查 vcpkg commit 是否固定（推荐用
git submodule add并 checkout 稳定 tag），避免 registry 更新导致端口名变更vcpkg
manifest mode 的复杂点不在配置本身，而在于它把“依赖生命周期”交还给了项目结构——一旦 vcpkg.json 移动、CMakeLists.txt 重命名、或 toolchain 路径写错，整个链路就静默失效，且错误提示极不直观。
