vckpg 安装使用

1. vcpkg 介绍

vcpkg 是微软 C++ 团队和社区共同维护的一款免费开源的 C/C++ 包管理器，支持 Windows、macOS 和 Linux 三大平台。它专为解决 C++ 库管理的痛点而设计，核心使用 C++ 和 CMake 脚本实现。

---

核心特点

1. 简单易用
   • 一键下载并构建流行库，自动处理上游依赖和版本冲突
   • 支持命令行操作或 vcpkg.json manifest 文件声明依赖 [[6]]
   • 提供详细文档和活跃的社区支持
2. 跨平台通用
   • 支持任意操作系统、构建系统（CMake/MSBuild/Makefile等）、目标架构、IDE 和 CI 流程
   • 库从源码构建，可按需配置
3. 可靠一致
   • 本地开发与 CI/CD 工作流保持一致
   • 可锁定依赖版本，团队共享依赖生态
4. 丰富生态
   • 当前注册表提供 2,773+ 个开源库端口（ports）
   • 支持创建私有 registry 管理自定义或企业内部库

🛠️ 关键概念

概念	说明
Ports	版本化的构建配方（CMake 脚本），描述如何下载、构建和安装一个库
Triplets	描述目标构建环境（CPU/OS/编译器/运行时等），默认提供 70+ 种配置，也支持自定义
Binary Caching	将构建好的包缓存，避免重复构建，加速团队和 CI 构建
Manifests	vcpkg.json 文件声明项目依赖，可纳入版本控制共享
Versioning	通过 baseline 机制管理兼容的版本集合，避免钻石依赖问题

2. 安装使用

2.1 安装 vcpkg

① 下载

# Windows (PowerShell)
git clone https://github.com/microsoft/vcpkg.git


# Linux/macOS
git clone https://github.com/microsoft/vcpkg.git

注意：此命令在 vcpkg 子目录中创建存储库的本地副本。 此位置是此 vcpkg 克隆的 vcpkg 根目录。

在安装这个之前需要先安装 git，参考文章：【2025年最新版】Git安装及环境配置超详细教程（以win11为例子）_git安装及配置教程

或者去官网下载压缩包也行，然后再解压

这里的话我安装的肯定就是 Windows 版本的了

② 安装

在 vcpkg 根目录下，运行 vcpkg 引导程序命令：

.\vcpkg\bootstrap-vcpkg.bat # Windows 使用
./vcpkg/bootstrap-vcpkg.sh  # Linux 使用

引导程序将使用 Microsoft C/C++ 工具、库和 Windows SDK 的位置配置 vcpkg。

安装过程如下：

PS D:\includes\vcpkg> .\bootstrap-vcpkg.bat
Downloading https://github.com/microsoft/vcpkg-tool/releases/download/2026-04-08/vcpkg.exe -> D:\includes\vcpkg\vcpkg.exe... done.
Validating signature... done.

vcpkg package management program version 2026-04-08-e0612b42ce44e55a0e630f2ee9d3c533a63d8bc1

See LICENSE.txt for license information.
Telemetry
---------
vcpkg collects usage data in order to help us improve your experience.
The data collected by Microsoft is anonymous.
You can opt-out of telemetry by re-running the bootstrap-vcpkg script with -disableMetrics,
passing --disable-metrics to vcpkg on the command line,
or by setting the VCPKG_DISABLE_METRICS environment variable.

Read more about vcpkg telemetry at docs/about/privacy.md

运行后结果：

• 脚本会自动下载并编译 vcpkg 核心程序
• 成功后会在当前目录生成 vcpkg.exe
• 之后即可使用 .\vcpkg install <库名> 安装第三方库

注意事项

1. 如果网络较慢或下载中断，可添加 --head 参数使用最新源码构建，或配置国内镜像/代理加速。
2. 引导完成后，推荐运行 .\vcpkg integrate install 将 vcpkg 注册到全局环境（VS/MSBuild 自动识别），或在 CMake 中通过工具链文件使用。

2.2 相关命令

Command	描述
vcpkg search [pat]	搜索可安装的包
vcpkg install <pkg>...	安装包
vcpkg remove <pkg>...	卸载包
vcpkg remove --outdated	卸载所有过期包
vcpkg list	列出已安装的包
vcpkg update	显示用于更新的包列表
vcpkg upgrade	重新生成所有过期包
vcpkg hash <file> [alg]	通过特定算法对文件执行哈希操作，默认为 SHA512
vcpkg integrate install	使已安装包在用户范围内可用。 首次使用时需要管理权限
vcpkg integrate remove	删除用户范围的集成
vcpkg integrate project	为使用单个 VS 项目生成引用 NuGet 包
vcpkg export <pkg>... [opt]...	导出包
vcpkg edit <pkg>	打开端口进行编辑（使用 %EDITOR%，默认为"code"）
vcpkg create <pkg> <url> [archivename]	创建新程序包
vcpkg cache	列出缓存的已编译包
vcpkg version	显示版本信息
vcpkg contact --survey	显示联系信息，以便发送反馈。

选项

选项	描述
--triplet <t>	指定目标体系结构三元组。 （默认：%VCPKG_DEFAULT_TRIPLET%，另请参阅 vcpkg help triplet）
--vcpkg-root <path>	指定 vcpkg 根目录（默认：%VCPKG_ROOT%）

2.3 全局使用 vcpkg（避免每次输 .\）

# 1. 将 vcpkg 添加到系统 PATH（临时）
$env:Path = "D:\includes\vcpkg;" + $env:Path

# 2. 或执行集成命令（推荐，对 Visual Studio/MSBuild 生效）
.\vcpkg integrate install

# 3. 之后就可以在任何位置直接使用：
vcpkg install nlohmann-json

3. 集成vcpkg

3.1 Windows 上的 Visual Studio 集成

从 vcpkg 根目录，运行 vcpkg integrate install 来配置 Visual Studio，以便按用户找到所有 vcpkg 头文件和二进制文件。 无需在 Visual Studio 中编辑 VC + + 目录路径。 如果有多个 vcpkg 克隆，则我们需从中运行此命令的克隆将成为新的默认位置。

现在，只需键入文件夹/标头名称即可轻松加入标头，并且自动完成功能将帮助完成这一切。 无需执行任何额外的步骤即可链接到库或添加项目引用。 下图演示了 Visual Studio 查找 azure-storage-cpp 标头的方法。 Vcpkg 将其标头置于 /installed 子文件夹中，由目标平台予以分区。

下图显示库的 /was 子文件夹中包含文件的列表：

3.2 Linux 或 macOS 上的 Visual Studio Code 集成

在 shell 或"终端"窗口中，将目录更改为 vcpkg 根目录。 然后运行./vcpkg integrate install，在 Linux 或 macOS 上配置 Visual Studio Code。 此命令将设置 vcpkg 工具和库的位置，并对源文件启用 IntelliSense。

3.3 删除 vcpkg 集成

如果已使用 integrate 选项，则应在删除 vcpkg 实例之前删除该集成。 若要删除和清理该集成，请将目录更改为 vcpkg 根目录。

• 在 Windows 上，运行 vcpkg integrate remove，确保清除该集成。
• 在 Linux 或 macOS 上，运行 ./vcpkg integrate remove 命令。

4. 示例

举例：我现在的场景是我需要 libpng 来进行开发，输入如下命令来安装，可以看到在开始自动下载。

# 安装依赖
.\vcpkg install libpng

注意我们可以使用.\vcpkg help triplet来看库支持的模式。

PS D:\includes\vcpkg> .\vcpkg help triplet
Built-in Triplets:
  arm-neon-android
  arm64-android
  arm64-linux
  arm64-osx
  arm64-windows-static-md
  arm64-windows
  x64-android
  x64-linux
  x64-windows-release
  x64-windows-static-md
  x64-windows-static
  x64-windows
  x86-windows
Community Triplets:
  arm-android
  arm-ios
  arm-linux-release
  arm-linux
  arm-mingw-dynamic
  arm-mingw-static
  arm-uwp-static-md
  arm-uwp
  arm-watchos
  arm-windows-static
  arm-windows
  arm64-android-release
  arm64-freebsd
  arm64-ios-release
  arm64-ios-simulator-release
  arm64-ios-simulator
  arm64-ios
  arm64-linux-dynamic
  arm64-linux-release
  arm64-mingw-dynamic
  arm64-mingw-static
  arm64-osx-dynamic
  arm64-osx-release
  arm64-tvos-simulator
  arm64-tvos
  arm64-uwp-static-md
  arm64-uwp
  arm64-visionos
  arm64-watchos-simulator
  arm64-watchos
  arm64-windows-static-release
  arm64-windows-static
  arm6432-watchos
  arm64ec-windows
  armv6-android
  loongarch32-linux-release
  loongarch32-linux
  loongarch64-linux-release
  loongarch64-linux
  mips64-linux
  ppc64le-linux-release
  ppc64le-linux
  riscv32-linux-release
  riscv32-linux
  riscv64-linux-release
  riscv64-linux
  s390x-linux-release
  s390x-linux
  wasm32-emscripten
  x64-freebsd-dynamic
  x64-freebsd-release
  x64-freebsd
  x64-ios
  x64-linux-dynamic
  x64-linux-release
  x64-mingw-dynamic-release
  x64-mingw-dynamic
  x64-mingw-static-release
  x64-mingw-static
  x64-netbsd
  x64-openbsd
  x64-osx-dynamic
  x64-osx-release
  x64-osx
  x64-solaris
  x64-tvos-simulator
  x64-uwp-static-md
  x64-uwp
  x64-watchos-simulator
  x64-windows-static-md-release
  x64-windows-static-release
  x64-xbox-scarlett-static
  x64-xbox-scarlett
  x64-xbox-xboxone-static
  x64-xbox-xboxone
  x86-android
  x86-freebsd
  x86-ios
  x86-linux
  x86-mingw-dynamic-release
  x86-mingw-dynamic
  x86-mingw-static-release
  x86-mingw-static
  x86-uwp-static-md
  x86-uwp
  x86-windows-static-md
  x86-windows-static
  x86-windows-v120
See https://learn.microsoft.com/vcpkg/users/triplets?WT.mc_id=vcpkg_inproduct_cli for more information.

删除库

.\vcpkg.exe remove jsoncpp

这个时候只是移除了默认的x86-winodws版本的文件，如果有其他平台的版本需要移除，需要制定相应的triplet。

移除也只是移除了二进制程序库而已，源码包和解压缩的源码并没有删除。

查看已经安装的列表

.\vcpkg.exe list

更新已经安装的开源库

一般有两种更新方式。

1. update指令，可以显示可以升级的开源库的列表。
2. upgrade的指令，会重新编译所有需要更新的包。

报错解决

问题一：Unable to find a valid Visual Studio instance

表示编译环境缺失

解决方案如下：

方案 1：安装 Visual Studio Build Tools（推荐，轻量）

这是微软官方提供的独立构建工具包，无需安装完整 VS IDE。

步骤：

1. 下载：https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/

2. 运行安装程序，务必勾选 ：

   • ✅ C++ 生成工具（核心编译器）
   • ✅ Windows 10/11 SDK（系统 API）
   • ✅ MSVC v143 生成工具（或最新版本）
   • ✅ C++ CMake 工具（可选，但推荐）

3. 安装完成后重启终端 （或执行 vswhere 验证）

4. 重试：

   .\vcpkg install openssl

验证是否安装成功：

# 方法 1：官方工具
vswhere -latest -requires Microsoft.Component.MSBuild

# 方法 2：检查编译器
where cl.exe
# 应返回类似: C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\...\cl.exe

方案 2：使用已安装的完整 Visual Studio

如果当前电脑已经安装了 Visual Studio 2019/2022（非 Build Tools）：

1. 打开 Visual Studio Installer
2. 点击 "修改" → 确保勾选：
   • 使用 C++ 的桌面开发 工作负载
   • Windows 10/11 SDK
3. 应用更改后重启终端
4. 重试安装

💡 完整 VS 和 Build Tools 可以共存，vcpkg 会自动检测最新/最合适的实例。