17370845950

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 是最常遇到的问题，多数源于“看似相同实则不同”的构建上下文。

• vcpkg 版本不一致：CI 脚本里用 git clone 拉最新 master，但缓存是基于某次特定 commit 打的。务必固定 vcpkg commit（如 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 内容、环境变量、甚至系统时区。少一个对齐点，缓存就变成摆设。