【CMake】[第十一篇]vcpkg 离线安装与 CMake 集成完整指南

vcpkg 离线安装与 CMake 集成完整指南

📋 目录

1. 前言
2. vcpkg 离线安装实战
3. vcpkg 与 CMake 的关系
4. CMake 项目中使用 vcpkg
5. 最佳实践
6. 常见问题

前言

在 C++ 项目开发中，依赖管理一直是一个痛点。vcpkg 作为微软推出的 C++ 包管理器，极大地简化了第三方库的安装和管理。然而，在实际开发中，我们经常遇到需要在离线环境中部署项目的情况。本文将详细介绍如何使用--no-downloads选项进行离线安装，并深入探讨 vcpkg 与 CMake 的集成关系。

vcpkg 离线安装实战

为什么需要离线安装？

在实际开发场景中，离线安装的需求很常见：

• 🏢企业内网环境：安全要求不允许直接访问外网
• 🚀CI/CD 环境：构建服务器可能没有外网访问权限
• 📦项目部署：需要将依赖打包到离线机器
• 🔒安全合规：某些行业要求完全离线部署

离线安装方法对比

vcpkg 提供了多种离线安装方法，各有优缺点：

使用 --no-downloads 离线安装完整流程

步骤 1：在线机器准备（有网络环境）

# 1. 设置下载目录（用于存储所有依赖文件）$env:VCPKG_DOWNLOADS ="D:\vcpkg-downloads"# 2. 可选：设置二进制缓存（推荐，可以加速离线安装）$env:VCPKG_BINARY_SOURCES ="files,D:/vcpkg-binary-cache,readwrite"# 3. 安装需要的包（会自动下载所有依赖到下载目录）vcpkg install libiconv:x64-windows# 4. 验证下载的文件dirD:\vcpkg-downloads# 应该看到：# - libiconv-*.tar.gz（源码包）# - cmake-*.zip（工具文件）# - 其他依赖文件

关键点：

• VCPKG_DOWNLOADS目录会存储所有源码包和工具文件
• 如果设置了二进制缓存，编译好的二进制文件会保存到缓存目录
• 建议同时准备两个目录：下载目录（源码）+ 二进制缓存（编译好的文件）

步骤 2：传输到离线机器

将以下目录复制到离线机器：

• D:\vcpkg-downloads- 下载目录（必需）
• D:\vcpkg-binary-cache- 二进制缓存目录（可选，但推荐）

传输方式：

• U盘/移动硬盘
• 内网文件服务器
• 打包压缩后传输

步骤 3：离线机器安装（无网络环境）

# 1. 设置下载目录（指向传输过来的目录）$env:VCPKG_DOWNLOADS ="D:\vcpkg-downloads"# 2. 可选：设置二进制缓存（如果传输了缓存目录）$env:VCPKG_BINARY_SOURCES ="files,D:/vcpkg-binary-cache,read"# 3. 使用 --no-downloads 强制离线安装vcpkg install libiconv:x64-windows--no-downloads

工作原理：

1. vcpkg 首先尝试从二进制缓存读取编译好的文件（如果设置了缓存）
2. 如果缓存不完整，会使用下载目录中的源码重新编译
3. --no-downloads确保不会尝试从网络下载任何文件

步骤 4：验证安装

# 检查安装的包vcpkg list# 应该看到：# libiconv:x64-windows 1.17 Character set conversion library

完整示例脚本

为了方便使用，可以创建一个批处理脚本：

@echo off REM 离线安装 libiconv 示例脚本 REM 设置下载目录 set VCPKG_DOWNLOADS=D:\vcpkg-downloads REM 可选：设置二进制缓存 set VCPKG_BINARY_SOURCES=files,D:/vcpkg-binary-cache,read REM 使用 --no-downloads 安装 vcpkg install libiconv:x64-windows --no-downloads if errorlevel 1 ( echo [错误] 安装失败！ echo 请检查： echo 1. 下载目录是否存在且完整 echo 2. 二进制缓存是否完整（如果使用了） pause exit /b 1 ) echo [成功] 安装完成！ vcpkg list | findstr libiconv

推荐配置：二进制缓存 + --no-downloads

最佳实践是同时使用二进制缓存和下载目录：

# 在线机器：准备两个目录$env:VCPKG_BINARY_SOURCES ="files,D:/vcpkg-binary-cache,readwrite"$env:VCPKG_DOWNLOADS ="D:\vcpkg-downloads"vcpkg install libiconv:x64-windows# 传输两个目录到离线机器# 离线机器：使用 --no-downloads$env:VCPKG_BINARY_SOURCES ="files,D:/vcpkg-binary-cache,read"$env:VCPKG_DOWNLOADS ="D:\vcpkg-downloads"vcpkg install libiconv:x64-windows--no-downloads

优势：

• ✅优先使用二进制缓存：如果缓存完整，直接使用，速度最快
• ✅后备方案：如果缓存不完整，使用下载目录中的源码重新编译
• ✅强制离线：--no-downloads确保不会意外下载
• ✅双重保障：即使缓存不完整也能成功安装

vcpkg 与 CMake 的关系

什么是 vcpkg？

vcpkg 是微软开发的 C++ 包管理器，类似于：

• Python 的pip
• Node.js 的npm
• Rust 的cargo

主要功能：

• 📦 管理 C++ 第三方库
• 🔧 自动处理依赖关系
• 🏗️ 自动编译和安装
• 🔗 与 CMake 无缝集成

什么是 CMake？

CMake 是一个跨平台的构建系统生成器，用于：

• 📝 编写构建配置（CMakeLists.txt）
• 🔨 生成各种构建系统文件（Visual Studio 项目、Makefile 等）
• 🎯 管理项目构建过程

vcpkg 与 CMake 的集成关系

vcpkg 和 CMake 是互补关系，共同构成了现代 C++ 项目的依赖管理和构建系统：

┌─────────────────────────────────────────┐ │ C++ 项目开发流程 │ ├─────────────────────────────────────────┤ │ │ │ vcpkg (依赖管理) │ │ ├─ 安装第三方库 │ │ ├─ 管理依赖关系 │ │ └─ 提供 CMake 配置文件 │ │ │ │ ↓ │ │ │ │ CMake (构建系统) │ │ ├─ 读取 CMakeLists.txt │ │ ├─ 使用 vcpkg 提供的库 │ │ └─ 生成构建文件 │ │ │ │ ↓ │ │ │ │ 编译器 (Visual Studio/GCC/Clang) │ │ └─ 编译生成可执行文件 │ │ │ └─────────────────────────────────────────┘

vcpkg 如何与 CMake 集成？

1. 工具链文件（Toolchain File）

vcpkg 提供了一个特殊的 CMake 工具链文件：vcpkg.cmake

位置：

<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

作用：

• 告诉 CMake 在哪里查找 vcpkg 安装的包
• 自动设置库路径、头文件路径等
• 提供find_package()的查找路径

2. CMake 配置机制

当使用 vcpkg 工具链文件时，CMake 会：

1. 读取 vcpkg 配置：

   # CMake 会自动读取 vcpkg 的配置 # 包括已安装的包、路径等信息

2. 设置查找路径：

   # vcpkg 会自动设置以下路径： # - CMAKE_PREFIX_PATH # - CMAKE_FIND_ROOT_PATH # - 库文件路径 # - 头文件路径

3. 提供包信息：

   # vcpkg 为每个包提供 CMake 配置文件 # 例如：zlib-config.cmake, zlib-targets.cmake

vcpkg 工具链文件的工作原理

# vcpkg.cmake 文件内部会做以下事情： # 1. 设置 vcpkg 安装目录 set(VCPKG_ROOT "D:/vcpkg") # 2. 设置已安装包的路径 set(VCPKG_INSTALLED_DIR "${VCPKG_ROOT}/installed") # 3. 设置查找路径 list(APPEND CMAKE_PREFIX_PATH "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}") # 4. 设置库文件路径 link_directories("${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/lib") # 5. 设置头文件路径 include_directories("${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/include")

CMake 项目中使用 vcpkg

方式一：命令行指定工具链文件（推荐）

# 配置 CMake 项目cmake-B build-S.`-DCMAKE_TOOLCHAIN_FILE=D:\vcpkg\scripts\buildsystems\vcpkg.cmake# 构建项目cmake--build build--config Release

优点：

• ✅ 不需要修改 CMakeLists.txt
• ✅ 灵活，可以为不同项目使用不同的 vcpkg 实例
• ✅ 适合 CI/CD 环境

方式二：在 CMakeLists.txt 中设置

cmake_minimum_required(VERSION 3.10) project(MyProject) # 设置工具链文件（必须在 project() 之前） set(CMAKE_TOOLCHAIN_FILE "D:/vcpkg/scripts/buildsystems/vcpkg.cmake" CACHE STRING "") # 或者使用环境变量 # set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake") project(MyProject) # 重新调用 project() 以应用工具链文件

注意：必须在project()之前设置工具链文件！

方式三：使用环境变量

# 设置环境变量$env:CMAKE_TOOLCHAIN_FILE ="D:\vcpkg\scripts\buildsystems\vcpkg.cmake"# CMake 会自动读取环境变量cmake-B build-S.

完整的 CMake 项目示例

CMakeLists.txt

cmake_minimum_required(VERSION 3.10) project(MyProject) # 设置 C++ 标准 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 查找 vcpkg 安装的包 find_package(ZLIB REQUIRED) find_package(libiconv REQUIRED) # 创建可执行文件 add_executable(myapp main.cpp) # 链接库 target_link_libraries(myapp PRIVATE ZLIB::ZLIB iconv::iconv )

main.cpp

#include<iostream>#include<zlib.h>#include<iconv.h>intmain(){std::cout<<"zlib version: "<<zlibVersion()<<std::endl;std::cout<<"Using libiconv"<<std::endl;return0;}

构建命令

# 1. 配置项目（指定 vcpkg 工具链文件）cmake-B build-S.`-DCMAKE_TOOLCHAIN_FILE=D:\vcpkg\scripts\buildsystems\vcpkg.cmake# 2. 构建项目cmake--build build--config Release# 3. 运行程序.\build\Release\myapp.exe

使用导出的包

如果使用vcpkg export导出的包：

# 导出包（在线机器）vcpkg export libiconv:x64-windows--raw--output-dir=D:\vcpkg-export# 传输到离线机器# 使用导出的包（离线机器）cmake-B build-S.`-DCMAKE_TOOLCHAIN_FILE=D:\vcpkg-export\vcpkg-export-20251217-100109\scripts\buildsystems\vcpkg.cmake

注意：导出的包包含日期文件夹，需要使用完整路径！

最佳实践

1. 项目结构建议

MyProject/ ├── CMakeLists.txt # CMake 配置文件 ├── src/ │ └── main.cpp # 源代码 ├── build/ # 构建目录（gitignore） └── README.md # 说明文档

2. CMakeLists.txt 最佳实践

cmake_minimum_required(VERSION 3.10) project(MyProject VERSION 1.0.0) # 设置 C++ 标准 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 查找依赖包 find_package(ZLIB REQUIRED) find_package(libiconv REQUIRED) # 创建目标 add_executable(myapp src/main.cpp) # 链接库（使用现代 CMake 方式） target_link_libraries(myapp PRIVATE ZLIB::ZLIB iconv::iconv ) # 设置包含目录（如果需要） target_include_directories(myapp PRIVATE src)

3. 离线安装最佳实践

在线机器准备：

# 1. 设置二进制缓存（加速离线安装）$env:VCPKG_BINARY_SOURCES ="files,D:/vcpkg-binary-cache,readwrite"# 2. 设置下载目录（存储源码）$env:VCPKG_DOWNLOADS ="D:\vcpkg-downloads"# 3. 安装所有需要的包vcpkg install libiconv:x64-windows zlib:x64-windows# 4. 验证安装vcpkg list

离线机器使用：

# 1. 设置环境变量$env:VCPKG_BINARY_SOURCES ="files,D:/vcpkg-binary-cache,read"$env:VCPKG_DOWNLOADS ="D:\vcpkg-downloads"# 2. 使用 --no-downloads 安装vcpkg install libiconv:x64-windows--no-downloads# 3. 配置 CMake 项目cmake-B build-S.`-DCMAKE_TOOLCHAIN_FILE=D:\vcpkg\scripts\buildsystems\vcpkg.cmake

4. 版本控制建议

应该提交：

• ✅CMakeLists.txt
• ✅ 源代码文件
• ✅README.md（包含依赖说明）

不应该提交：

• ❌build/目录
• ❌vcpkg_installed/目录
• ❌ 编译生成的文件

.gitignore示例：

build/ vcpkg_installed/ *.exe *.dll *.lib *.obj

常见问题

Q1: 为什么必须使用工具链文件？

A: vcpkg 安装的包不在系统默认路径中，CMake 需要通过工具链文件知道在哪里查找这些包。

Q2: 工具链文件必须在 project() 之前设置吗？

A: 是的！工具链文件必须在project()之前设置，否则 CMake 无法正确配置查找路径。

Q3: 可以使用多个 vcpkg 实例吗？

A: 可以！每个项目可以指定不同的 vcpkg 工具链文件，使用不同的包集合。

Q4: 离线安装失败怎么办？

检查清单：

1. ✅ 下载目录是否存在且完整？
2. ✅ 二进制缓存是否完整（如果使用了）？
3. ✅ 编译器版本是否匹配？
4. ✅ 架构是否匹配（x64-windows vs x86-windows）？
5. ✅ 是否使用了--no-downloads选项？

Q5: 如何查看 vcpkg 安装的包？

# 列出所有已安装的包vcpkg list# 搜索包vcpkg search zlib# 查看包的详细信息vcpkg show zlib

Q6: CMake 找不到 vcpkg 安装的包？

解决方案：

1. 确认工具链文件路径正确
2. 确认包已正确安装：vcpkg list
3. 确认包名正确（区分大小写）
4. 检查 CMake 版本是否支持该包

Q7: 如何更新 vcpkg 和已安装的包？

# 更新 vcpkg 本身cd D:\vcpkg git pull.\bootstrap-vcpkg.bat# 更新已安装的包vcpkg upgrade--no-dry-run

总结

vcpkg 离线安装要点

1. 准备阶段（在线机器）：

   • 设置VCPKG_DOWNLOADS下载目录
   • 可选：设置VCPKG_BINARY_SOURCES二进制缓存
   • 安装需要的包

2. 传输阶段：

   • 复制下载目录到离线机器
   • 可选：复制二进制缓存目录

3. 安装阶段（离线机器）：

   • 设置相同的环境变量
   • 使用--no-downloads强制离线安装

vcpkg 与 CMake 的关系

• vcpkg：负责依赖管理（安装、更新、卸载包）
• CMake：负责构建系统（编译、链接项目）
• 工具链文件：连接两者的桥梁，让 CMake 知道在哪里查找 vcpkg 安装的包

推荐工作流程

1. 开发环境：使用 vcpkg 在线安装依赖
2. 离线部署：使用--no-downloads+ 二进制缓存 + 下载目录
3. CI/CD：在构建脚本中指定工具链文件路径

参考资料

• vcpkg 官方文档
• CMake 官方文档
• vcpkg GitHub 仓库

希望这篇指南能帮助你更好地理解和使用 vcpkg 进行离线安装，以及它与 CMake 的集成关系！