vcpkg binary caching 能跳过源码编译，直接解压安装预构建二进制包，耗时从分钟级降至秒级；但要求 vcpkg commit、triplet、工具链、环境变量等所有缓存 key 严格一致，否则缓存失效。
什么是 vcpkg binary caching，它真能跳过源码编译？
vcpkg binary caching 不是“跳过构建”，而是跳过 vcpkg install 过程中重复的源码下载、配置、编译、打包全流程。只要缓存命中（即已存在完全匹配的二进制包），vcpkg 就直接解压安装，耗时从分钟级降到秒级。
关键前提是：缓存 key 必须严格一致——包括 vcpkg commit hash、端口版本、triplet、主机 triplet、CMake 工具链、环境变量（如 VCPKG_FORCE_SYSTEM_BINARIES）、甚至 vcpkg.json 中的依赖哈希。任意一项变动都会导致 miss。
如何配置 CI 环境启用 binary caching？
核心是两步：1）让 vcpkg 知道缓存位置；2）确保所有 CI job 共享同一缓存路径且权限可控。不推荐用默认本地缓存（vcpkg-root/installed/），因为每次 CI 都是干净环境。
- 设置环境变量
VCPKG_BINARY_SOURCES指向远程缓存（如 Azure Blob、GitHub Packages、S3 或本地 HTTP 服务器），格式为：clear;nuget,https://example.com/vcpkg-cache（clear表示清空本地缓存优先查远程） - 若用 GitHub Actions，推荐搭配
actions/cache缓存vcpkg-root/.cache目录（注意不是installed/），这是 vcpkg 存放二进制包元数据和临时归档的地方 - 必须在
vcpkg install前运行vcpkg integrate install或确保VCPKG_ROOT正确，否则缓存逻辑可能被绕过
为什么 CI 中 binary cache 总是 miss？常见陷阱有哪些？
缓存 miss 是最常遇到的问题，多数源于“看似相同实则不同”的构建上下文。
立即学习“C++免费学习笔记（深入）”；
-
vcpkg版本不一致：CI 脚本里用git clone拉最新 master，但缓存是基于某次特定 commit 打的。务必固定vcpkgcommit（如git -C vcpkg checkout f0a3b4c）并写死在 CI 配置中 - triplet 名称拼写差异：比如
x64-windows和x64-windows-static-md是完全不同的缓存 key；CI 中未显式指定--triplet，vcpkg 可能 fallback 到默认值（受VCPKG_DEFAULT_TRIPLET影响） - 端口覆盖（overlay ports）未同步：如果项目用了自定义 port（
--overlay-ports），这些 port 的内容变更不会触发缓存 key 自动更新，需手动清空或重命名 overlay 目录 - CI runner 系统时间偏差过大：vcpkg 会校验远程缓存包的
last-modified时间戳，偏差 >5 分钟可能导致拒绝使用
如何验证 binary cache 是否真正生效？
别只看日志里有没有 “Using cached binary package” —— 它可能来自本地临时缓存而非你配的远程源。
加两个参数强制可观测：
vcpkg install zlib --debug --binarysource="clear;nuget,https://your-cache.com"
观察输出中是否出现：
Downloading binary archive from https://your-cache.com/...Using cached binary package zlib:x64-windows@1.2.12#14- 没有
Starting package extraction或Building package的冗长日志
如果看到 Failed to fetch from nuget source 但后续仍成功安装，说明 fallback 到了本地构建——你的缓存配置没起作用，或者网络/认证失败后被静默忽略。
binary caching 的成败不在配置多复杂，而在所有参与构建的环节是否对“一致性”有明确共识：vcpkg 版本、triplet、overlay 内容、环境变量、甚至系统时区。少一个对齐点，缓存就变成摆设。
