Win10+VS2019配置vcpkg：从安装到项目集成的完整指南

1. 为什么你需要vcpkg？

如果你经常在Windows下用C++开发，肯定遇到过这样的场景：想用个第三方库，结果发现要自己编译、配置路径、处理依赖关系，折腾半天还可能编译失败。vcpkg就是微软推出的C++包管理工具，它能像Python的pip一样，一条命令搞定库的下载、编译和配置。

我最早接触vcpkg是在2017年，当时为了在VS2017里用OpenCV，手动配置了整整一上午。后来用了vcpkg，只需要vcpkg install opencv，三分钟就搞定了所有环境配置。现在vcpkg已经支持超过4500个开源库，从常用的Boost、Qt到冷门的数学计算库都能一键安装。

2. 环境准备与安装

2.1 基础环境检查

在开始前，请确认你的系统满足：

• Windows 10 版本1903或更高
• Visual Studio 2019（建议16.9+）
• Git客户端（可选但推荐）

特别提醒：VS2019安装时要勾选"使用C++的桌面开发"工作负载，确保包含英文语言包（否则可能遇到编码问题）。

2.2 安装vcpkg

打开PowerShell（管理员权限），执行以下命令：

bash复制# 克隆仓库（建议放在非系统盘）
cd D:
git clone https://github.com/microsoft/vcpkg
cd vcpkg

# 执行引导脚本
.\bootstrap-vcpkg.bat

如果网络不好导致下载失败，可以：

1. 手动下载vcpkg.exe放到目录
2. 创建downloads文件夹，把提前下好的依赖包放进去

2.3 配置环境变量

把vcpkg目录（如D:\vcpkg）添加到系统PATH变量。这样可以在任意位置使用vcpkg命令。

小技巧：如果想默认安装x64版本库，可以新增系统变量VCPKG_DEFAULT_TRIPLET=x64-windows

3. 基础使用指南

3.1 搜索和安装库

查看所有可用库：

bash复制vcpkg search > libraries.txt

安装一个库（以jsoncpp为例）：

bash复制# 默认安装x86版本
vcpkg install jsoncpp

# 指定安装x64版本
vcpkg install jsoncpp:x64-windows

3.2 管理已安装的库

列出已安装的库：

bash复制vcpkg list

卸载某个库：

bash复制vcpkg remove jsoncpp
# 完全删除（包括源码）
vcpkg remove --purge jsoncpp

3.3 解决常见安装问题

如果遇到下载超时：

1. 找到日志中的下载链接，用迅雷等工具下载
2. 将文件放到vcpkg/downloads目录
3. 重新执行安装命令

对于需要特定编译选项的库，可以使用--feature参数：

bash复制vcpkg install opencv[contrib,ffmpeg]:x64-windows

4. VS2019项目集成

4.1 全局集成（适合快速原型开发）

bash复制vcpkg integrate install

这会自动将所有已安装库的路径添加到VS的全局设置中。打开任意项目都能直接#include头文件。

注意：全局集成可能导致项目间依赖冲突，生产环境慎用

4.2 按项目集成（推荐方式）

方法1：通过NuGet集成

bash复制# 生成配置文件
vcpkg integrate project

然后在VS2019中：

1. 工具 > NuGet包管理器 > 程序包管理器设置
2. 添加新源，路径选择<vcpkg_dir>\scripts\buildsystems
3. 在项目上右键 > 管理NuGet程序包，选择vcpkg源安装

方法2：CMake项目集成

在CMakeLists.txt开头添加：

cmake复制set(CMAKE_TOOLCHAIN_FILE 
    "D:/vcpkg/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "Vcpkg toolchain file")

4.3 实际项目配置示例

假设我们要创建一个使用jsoncpp和fmt库的控制台项目：

1. 创建vcpkg.json文件：

json复制{
  "dependencies": [
    "jsoncpp",
    "fmt"
  ]
}

2. 在VS2019中：

• 右键项目 > 属性 > Vcpkg
• 勾选"使用Vcpkg清单"
• 设置目标平台为x64

3. 代码中直接包含头文件：

cpp复制#include <json/json.h>
#include <fmt/format.h>
// 无需手动配置库路径！

5. 高级技巧与最佳实践

5.1 自定义编译选项

创建triplets文件（如x64-windows-custom.h）：

cmake复制set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)  # 强制静态链接

使用时：

bash复制vcpkg install zlib:x64-windows-custom

5.2 导出和共享库

将已安装库打包：

bash复制# 导出为7z压缩包
vcpkg export jsoncpp fmt --7zip --output=my_libs

# 导出为NuGet包
vcpkg export --nuget all

5.3 版本控制

在vcpkg.json中指定精确版本：

json复制{
  "dependencies": [
    {
      "name": "boost",
      "version>=": "1.81.0"
    },
    {
      "name": "opencv",
      "version": "4.5.5"
    }
  ]
}

6. 性能优化建议

1. 二进制缓存：在vcpkg-configuration.json中添加：

json复制{
  "default-registry": { ... },
  "binary-caching": true
}

2. 并行编译：安装时添加--x-use-aria2参数启用多线程下载：

bash复制vcpkg install opencv --x-use-aria2

3. 镜像源配置：创建vcpkg-configuration.json：

json复制{
  "registries": [
    {
      "kind": "git",
      "repository": "https://mirror.ghproxy.com/https://github.com/microsoft/vcpkg",
      "baseline": "a1ec64f"
    }
  ]
}

7. 常见问题排查

Q1：安装时报错"Could not find compiler"

• 检查VS2019英文语言包是否安装
• 确保PATH中有VS的VC工具链路径

Q2：项目找不到头文件

• 执行vcpkg integrate remove后重新安装
• 检查项目平台是否与库平台匹配（x86/x64）

Q3：链接时报LNK2005错误

• 可能是全局集成导致的多版本冲突，改用项目级集成
• 检查库的链接方式（静态/动态）是否一致

最后分享一个实用命令，查看库的依赖关系：

bash复制vcpkg depend-info boost