微软vcpkg包管理工具如何使用？

VCPKG 使用说明文档

简介

vcpkg 是微软开发的开源 C/C++ 包管理器，旨在简化 Windows、Linux 和 macOS 上的 C/C++ 库的获取、编译和使用过程。它提供了大量的预编译库，并支持跨平台编译，使得开发者能够轻松地在项目中集成第三方库。

vcpkg 具有以下特点：

• 支持 Windows、Linux、macOS 等多个平台
• 提供超过 1500 个常用 C/C++ 库的预编译版本
• 支持静态链接和动态链接
• 支持交叉编译，可在 Linux 上编译 Windows 库
• 提供两种使用模式：经典模式和清单模式
• 支持二进制缓存，加快构建速度
• 易于集成到现有项目中

本文档将详细介绍 vcpkg 的安装、配置和使用方法，帮助开发者快速上手并高效使用 vcpkg 管理项目依赖。

镜像源替换

将默认的 github.com 替换为 bgithub.xyz 可以提高部分库的下载速度，避免因为网络问题导致的下载失败。

# Windows (PowerShell)
$env:VCPKG_DOWNLOAD_MIRROR = "https://bgithub.xyz"# Linux/macOS
export VCPKG_DOWNLOAD_MIRROR="https://bgithub.xyz"

跨平台编译依赖(Ubuntu 24.04.3 LTS-X86_64)

本篇文章以 Ubuntu 24.04.3 LTS 为例，介绍如何在 Ubuntu 上编译 Windows 平台的库。大家也可以举一反三来在其他平台上编译与宿主机不同平台的库。

# Ubuntu -> Windows
apt install -y nasm mingw-w64 mingw-w64-x86-64-dev mingw-w64-tools mingw-w64-i686-dev mingw-w64-x86-64-dev cmake make ninja-build nasm yasm pkg-config

vcpkg参数说明

参数分类	参数	功能简介
基本控制	--dry-run	模拟安装过程，仅显示计划，不实际执行。
	--keep-going	某个包安装失败时，继续安装不依赖于它的其他包。
	--recurse	批准在安装过程中移除和重建包的计划。
下载与缓存	--no-downloads	仅使用已缓存的资源，禁止下载新内容。
	--only-downloads	仅下载资源，不进行构建。
	--only-binarycaching	仅从二进制缓存恢复包，若缓存中没有则失败。
	--head	(经典模式) 安装上游最新的代码（而非稳定版本）。
清理选项	--clean-after-build	构建每个包后，清理编译临时文件、包文件和下载缓存。
	--clean-buildtrees-after-build	构建每个包后，清理编译临时目录（buildtrees）。
	--clean-packages-after-build	构建每个包后，清理临时包目录（packages）。
	--clean-downloads-after-build	构建每个包后，清理下载缓存（downloads）。
路径定制	--triplet=<t>	指定目标平台三元组（Target Triplet），例如 x64-windows。
	--host-triplet=<t>	指定主机平台三元组（Host Triplet）。
	--overlay-ports=<path>	指定覆盖端口（Overlay Ports）的目录。
	--overlay-triplets=<path>	指定覆盖三元组（Overlay Triplets）的目录。
	--vcpkg-root=<path>	指定vcpkg的根目录。
	--downloads-root=<path>	指定下载缓存目录，替代默认的 downloads/。
高级功能	--editable	(经典模式) 启用可编辑构建，保留源代码以便修改。
	--enforce-port-checks	将端口检测到的问题或使用已弃用功能的行为视为错误。
	--allow-unsupported	对不支持的端口发出警告而非停止。
	--classic	即使发现清单（vcpkg.json），也强制使用经典模式。
	--no-print-usage	安装结束后不打印使用说明。
实验性功能 (以 --x- 开头)	--x-feature=<feature>	(清单模式) 安装清单中指定的额外功能（Feature）的依赖。
	--x-no-default-features	(清单模式) 不安装清单中定义的默认功能（Default Features）。
	--x-buildtrees-root	(实验性) 指定 buildtrees 目录路径。
	--x-install-root	(实验性) 指定 installed 目录路径。
	--x-packages-root	(实验性) 指定 packages 目录路径。
	--x-write-nuget-packages-config	(实验性) 写出用于二进制缓存的 NuGet packages.config 格式文件。
	--x-asset-sources	(实验性) 指定资源缓存源。
二进制/资源缓存	--binarysource=...	指定二进制缓存源。

💡 核心概念与使用场景

• 经典模式 vs 清单模式：vcpkg有两种主要工作模式。

  • 经典模式：通过命令行直接安装包，如 vcpkg install libheif:x64-windows。
  • 清单模式：在项目目录下使用 vcpkg.json 文件声明项目依赖，然后运行 vcpkg install 来安装所有依赖。--classic 选项可以强制在存在清单文件的目录下使用经典模式。

• 常用场景举例：

  • 查看安装计划：在安装前，使用 vcpkg install <包名> --dry-run 可以预览vcpkg将要执行的操作，包括安装哪些包及其依赖，而不会实际构建。
  • 节省磁盘空间：在持续集成等自动化环境中，使用 --clean-after-build 可以在每个包构建完成后清理中间文件，有效减少磁盘占用。
  • 处理安装失败：当安装一个包含多个包的命令时，如果某个包构建失败，使用 --keep-going 可以让vcpkg继续尝试安装其他不依赖于这个失败包的库。
  • 离线或受限环境：组合使用 --only-downloads 提前下载所有资源，然后在离线环境中使用 --no-downloads 进行构建。

# 使用示例
./vcpkg install libheif:x64-windows-linux --x-install-root=./heif# 解释：
x64-windows-linux --> [.cmake自定义配置文件名]
--x-install-root=./heif --> [指定安装根目录为./heif，将所有安装的库文件和头文件放入该目录下。]

自定义配置

自定义配置文件可以帮助你在不同平台之间切换编译选项，例如在 Ubuntu 上编译 Windows 平台的库。

<!-- 在目录triplets/community/下可自行创建.cmake配置文件例如： -->touch triplets/community/x64-windows-linux.cmake<!-- 以 Ubuntu 24.04.3 LTS 为例，跨平台编译配置 -->
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)# 关键配置：指定为 Windows 系统
set(VCPKG_CMAKE_SYSTEM_NAME Windows)# 指定 MinGW 交叉编译工具链
set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "/home/xt/gitbase/vcpkg-2025.10.17/scripts/toolchains/mingw.cmake")# 设置 MinGW 路径（根据您的实际安装路径调整）
set(CMAKE_C_COMPILER "/usr/bin/x86_64-w64-mingw32-gcc")
set(CMAKE_CXX_COMPILER "/usr/bin/x86_64-w64-mingw32-g++")

🚀 项目初始化与基本使用流程

1. 初始化 vcpkg

首次使用 vcpkg 需要先进行初始化：

# 克隆 vcpkg 仓库
git clone https://github.com/Microsoft/vcpkg.git# 进入 vcpkg 目录并运行引导程序
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# 或
./bootstrap-vcpkg.bat # Windows

2. 搜索和安装包

# 搜索可用的包
./vcpkg search <关键字># 查看包的详细信息
./vcpkg show <包名># 安装包（以 zlib 为例）
./vcpkg install zlib# 安装特定平台的包
./vcpkg install zlib:x64-windows
./vcpkg install zlib:x64-linux

3. 集成到项目中

经典模式集成

# 获取集成指令
./vcpkg integrate install# 移除集成
./vcpkg integrate remove

CMake 项目集成

在 CMakeLists.txt 中添加：

# 方法1：使用工具链文件（推荐）
cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..# 方法2：在 CMakeLists.txt 中手动指定
set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} /path/to/vcpkg/installed/x64-windows/share)
find_package(ZLIB REQUIRED)
target_link_libraries(main PRIVATE ZLIB::ZLIB)

🔧 常见 triplet 配置示例

Windows 平台配置

# x64-windows.cmake
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)

Linux 平台配置

# x64-linux.cmake
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME Linux)

静态链接 Windows 配置

# x64-windows-static.cmake
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE static)
set(VCPKG_LIBRARY_LINKAGE static)

Android ARM64 配置

# arm64-android.cmake
set(VCPKG_TARGET_ARCHITECTURE arm64)
set(VCPKG_CRT_LINKAGE static)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
set(VCPKG_ANDROID_API_LEVEL 21)

📦 清单模式 (Manifest Mode)

使用 vcpkg.json 文件管理项目依赖：

{"name": "my-application","version-string": "1.0.0","dependencies": ["zlib","fmt",{"name": "boost","features": ["asio", "filesystem"]}],"builtin-baseline": "a14a6cdc794389eb1abacee13817b83481072735"
}

然后运行：

./vcpkg install

🔄 版本控制

vcpkg 支持多种版本控制方式：

Git 标签版本

{"dependencies": [{"name": "zlib","version>=": "1.2.11"}]
}

SHA 版本

{"dependencies": [{"name": "zlib","version=": "1.2.11","port-version": 0}],"builtin-baseline": "a14a6cdc794389eb1abacee13817b83481072735"
}

💾 二进制缓存

为了加速构建过程，可以使用二进制缓存：

# 启用本地二进制缓存
./vcpkg install <包名> --binarysource=files,/path/to/cache# 启用 NuGet 二进制缓存
./vcpkg install <包名> --binarysource=nuget,<feed-url>

❓ 常见问题解答

Q: 如何解决下载失败问题？

A: 可以设置镜像源或使用代理：

# 设置镜像源
export VCPKG_DOWNLOAD_MIRROR="https://mirrors.cloud.tencent.com/vcpkg"# 设置代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Q: 如何更新 vcpkg 和包列表？

A:

# 更新 vcpkg
git pull# 更新包列表
./vcpkg update

Q: 如何卸载已安装的包？

A:

# 卸载特定包
./vcpkg remove <包名># 卸载所有包
./vcpkg remove --outdated

Q: 如何查看已安装的包？

A:

# 列出所有已安装的包
./vcpkg list# 查看特定包的信息
./vcpkg info <包名>

Q: 如何创建自己的包？

A: 参考官方文档创建端口文件：

1. 创建端口目录：ports/<包名>/
2. 编写 portfile.cmake 文件
3. 创建 vcpkg.json 清单文件
4. 测试安装：./vcpkg install <包名>

🛠 高级技巧

1. 使用 Overlay Ports

可以覆盖官方端口或添加私有端口：

./vcpkg install <包名> --overlay-ports=/path/to/custom/ports

2. 使用 Overlay Triplets

可以使用自定义的 triplet 配置：

./vcpkg install <包名> --overlay-triplets=/path/to/custom/triplets

3. 环境变量配置

常用的环境变量：

# 设置默认 triplet
export VCPKG_DEFAULT_TRIPLET=x64-windows# 禁用指标收集
export VCPKG_DISABLE_METRICS=1# 设置下载缓存目录
export VCPKG_DOWNLOADS_ROOT=/path/to/downloads

4. 调试构建问题

# 查看详细的构建日志
./vcpkg install <包名> --debug# 仅下载源码不构建
./vcpkg install <包名> --only-downloads# 保持构建树以便调试
./vcpkg install <包名> --no-clean-after-build