vcpkg 离线安装与 CMake 集成完整指南
📋 目录
- 前言
- vcpkg 离线安装实战
- vcpkg 与 CMake 的关系
- CMake 项目中使用 vcpkg
- 最佳实践
- 常见问题
前言
在 C++ 项目开发中，依赖管理一直是一个痛点。vcpkg 作为微软推出的 C++ 包管理器，极大地简化了第三方库的安装和管理。然而，在实际开发中，我们经常遇到需要在离线环境中部署项目的情况。本文将详细介绍如何使用--no-downloads选项进行离线安装，并深入探讨 vcpkg 与 CMake 的集成关系。
vcpkg 离线安装实战
为什么需要离线安装？
在实际开发场景中，离线安装的需求很常见：
- 🏢企业内网环境：安全要求不允许直接访问外网
- 🚀CI/CD 环境：构建服务器可能没有外网访问权限
- 📦项目部署：需要将依赖打包到离线机器
- 🔒安全合规：某些行业要求完全离线部署
离线安装方法对比
vcpkg 提供了多种离线安装方法，各有优缺点：
| 方法 | 命令 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 导出/导入 | vcpkg export | 独立完整，可直接使用 | 需要处理日期文件夹 | 一次性部署 |
| 二进制缓存 | vcpkg install（设置缓存） | 最快，无需编译 | 需要预先配置 | 频繁安装 |
| –no-downloads | vcpkg install --no-downloads | 简单，强制离线 | 需要重新编译 | 完全离线环境 |
使用 --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工作原理：
- vcpkg 首先尝试从二进制缓存读取编译好的文件（如果设置了缓存）
- 如果缓存不完整，会使用下载目录中的源码重新编译
--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 会：
读取 vcpkg 配置：
# CMake 会自动读取 vcpkg 的配置 # 包括已安装的包、路径等信息设置查找路径：
# vcpkg 会自动设置以下路径： # - CMAKE_PREFIX_PATH # - CMAKE_FIND_ROOT_PATH # - 库文件路径 # - 头文件路径提供包信息：
# 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.cmake4. 版本控制建议
应该提交：
- ✅
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: 离线安装失败怎么办？
检查清单：
- ✅ 下载目录是否存在且完整？
- ✅ 二进制缓存是否完整（如果使用了）？
- ✅ 编译器版本是否匹配？
- ✅ 架构是否匹配（x64-windows vs x86-windows）？
- ✅ 是否使用了
--no-downloads选项？
Q5: 如何查看 vcpkg 安装的包？
# 列出所有已安装的包vcpkg list# 搜索包vcpkg search zlib# 查看包的详细信息vcpkg show zlibQ6: CMake 找不到 vcpkg 安装的包？
解决方案：
- 确认工具链文件路径正确
- 确认包已正确安装：
vcpkg list - 确认包名正确（区分大小写）
- 检查 CMake 版本是否支持该包
Q7: 如何更新 vcpkg 和已安装的包？
# 更新 vcpkg 本身cd D:\vcpkg git pull.\bootstrap-vcpkg.bat# 更新已安装的包vcpkg upgrade--no-dry-run总结
vcpkg 离线安装要点
准备阶段（在线机器）：
- 设置
VCPKG_DOWNLOADS下载目录 - 可选：设置
VCPKG_BINARY_SOURCES二进制缓存 - 安装需要的包
- 设置
传输阶段：
- 复制下载目录到离线机器
- 可选：复制二进制缓存目录
安装阶段（离线机器）：
- 设置相同的环境变量
- 使用
--no-downloads强制离线安装
vcpkg 与 CMake 的关系
- vcpkg：负责依赖管理（安装、更新、卸载包）
- CMake：负责构建系统（编译、链接项目）
- 工具链文件：连接两者的桥梁，让 CMake 知道在哪里查找 vcpkg 安装的包
推荐工作流程
- 开发环境：使用 vcpkg 在线安装依赖
- 离线部署：使用
--no-downloads+ 二进制缓存 + 下载目录 - CI/CD：在构建脚本中指定工具链文件路径
参考资料
- vcpkg 官方文档
- CMake 官方文档
- vcpkg GitHub 仓库
希望这篇指南能帮助你更好地理解和使用 vcpkg 进行离线安装，以及它与 CMake 的集成关系！
