微软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 可以提高部分库的下载速度，避免因为网络问题导致的下载失败。

bash 复制代码

# 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 平台的库。大家也可以举一反三来在其他平台上编译与宿主机不同平台的库。

bash 复制代码

# 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 进行构建。

bash 复制代码

# 使用示例
./vcpkg install libheif:x64-windows-linux --x-install-root=./heif

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

自定义配置

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

txt 复制代码

<!-- 在目录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 需要先进行初始化：

bash 复制代码

# 克隆 vcpkg 仓库
git clone https://github.com/Microsoft/vcpkg.git

# 进入 vcpkg 目录并运行引导程序
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# 或
./bootstrap-vcpkg.bat # Windows

2. 搜索和安装包

bash 复制代码

# 搜索可用的包
./vcpkg search <关键字>

# 查看包的详细信息
./vcpkg show <包名>

# 安装包（以 zlib 为例）
./vcpkg install zlib

# 安装特定平台的包
./vcpkg install zlib:x64-windows
./vcpkg install zlib:x64-linux

3. 集成到项目中

经典模式集成

bash 复制代码

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

# 移除集成
./vcpkg integrate remove

CMake 项目集成

在 CMakeLists.txt 中添加：

cmake 复制代码

# 方法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 平台配置

cmake 复制代码

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

Linux 平台配置

cmake 复制代码

# 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 配置

cmake 复制代码

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

Android ARM64 配置

cmake 复制代码

# 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 文件管理项目依赖：

json 复制代码

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

然后运行：

bash 复制代码

./vcpkg install

🔄 版本控制

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

Git 标签版本

json 复制代码

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

SHA 版本

json 复制代码

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

💾 二进制缓存

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

bash 复制代码

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

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

❓ 常见问题解答

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

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

bash 复制代码

# 设置镜像源
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 和包列表？

bash 复制代码

# 更新 vcpkg
git pull

# 更新包列表
./vcpkg update

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

bash 复制代码

# 卸载特定包
./vcpkg remove <包名>

# 卸载所有包
./vcpkg remove --outdated

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

bash 复制代码

# 列出所有已安装的包
./vcpkg list

# 查看特定包的信息
./vcpkg info <包名>

Q: 如何创建自己的包？

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

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

🛠 高级技巧

1. 使用 Overlay Ports

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

bash 复制代码

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

2. 使用 Overlay Triplets

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

bash 复制代码

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

3. 环境变量配置

常用的环境变量：

bash 复制代码

# 设置默认 triplet
export VCPKG_DEFAULT_TRIPLET=x64-windows

# 禁用指标收集
export VCPKG_DISABLE_METRICS=1

# 设置下载缓存目录
export VCPKG_DOWNLOADS_ROOT=/path/to/downloads

4. 调试构建问题

bash 复制代码

# 查看详细的构建日志
./vcpkg install <包名> --debug

# 仅下载源码不构建
./vcpkg install <包名> --only-downloads

# 保持构建树以便调试
./vcpkg install <包名> --no-clean-after-build