vcpkg binary caching 是将构建好的二进制产物缓存以复用、避免重复编译的机制；它默认不启用，需手动配置 vcpkg_binary_sources 环境变量指向本地或共享路径。
什么是 vcpkg binary caching，为什么它不是开箱即用的
vcpkg 默认不启用二进制缓存，每次 vcpkg install 都会从源码重新构建——哪怕你刚装过同一个 triplet 的同一个库。binary caching 的作用就是把构建好的二进制产物（.exe/.dll/.a/.lib 等）存起来，下次直接复用，省去编译时间。但它需要你显式配置存储位置和共享策略，vcpkg 本身不帮你自动开启。
如何启用本地 binary cache（最常用场景）
只需两步：设置环境变量 + 初始化缓存目录。vcpkg 通过 VCPKG_BINARY_SOURCES 控制缓存行为，值格式为 files,<em>路径</em> 或 nuget,<em>源地址</em>；本地缓存用 files 即可。
- Windows：在命令行运行
set VCPKG_BINARY_SOURCES=files,C: cpkg-cache，或永久写入系统环境变量 - Linux/macOS：在 shell 中执行
export VCPKG_BINARY_SOURCES="files:/home/you/vcpkg-cache"，建议加到~/.bashrc或~/.zshrc - 确保目标路径存在且可读写，vcpkg 不会自动创建父目录
- 首次启用后，
vcpkg install会自动将新构建的包存入该目录，后续安装相同triplet+port组合时直接提取
常见错误：cache 不生效的几个典型原因
明明设了 VCPKG_BINARY_SOURCES，但还是每次都编译？大概率是这几个点没对上：
-
VCPKG_BINARY_SOURCES拼写错误（比如多一个下划线、大小写混用），vcpkg 完全忽略该变量，静默回退到无缓存模式 - 路径中含空格或中文，Windows 下尤其容易出问题；建议用短英文路径，如
C: cpkg-cache - 用了
--clean-after-build或设置了VCPKG_KEEP_ENV_VARS=1但没保留VCPKG_BINARY_SOURCES，导致子进程丢失变量 - 不同 vcpkg 版本之间缓存不兼容——vcpkg 会在缓存目录里存 hash 校验信息，升级 vcpkg 后旧缓存可能被跳过（不会报错，但也不用）
多个团队共用 binary cache 怎么做（简单共享方案）
想让 CI 或同事复用你的构建结果？不需要搭 nuget server，用网络共享文件夹 + files 协议就能跑通，前提是路径可达且权限一致。
- Windows 共享目录：设好 SMB 共享（如
\server cpkg-cache），然后设置VCPKG_BINARY_SOURCES=files,\server cpkg-cache - Linux/macOS：挂载 NFS 或 Samba 到本地路径（如
/mnt/vcpkg-cache），再指向该路径 - 必须保证所有机器访问该路径时，看到的文件内容完全一致（避免符号链接、不同挂载选项导致 stat 时间戳/权限差异）
- vcpkg 对缓存文件加了校验，但不校验路径本身的访问一致性——如果某台机器因权限问题读不到某个 .zip，它会悄悄跳过并重新构建，不会报错提示
binary cache 的核心逻辑很朴素：按 port 名 + triplet + 构建参数生成唯一 key，查不到就编译，查到了就解压。真正难的是路径稳定性、环境变量传递和跨平台权限对齐——这些地方一松动，cache 就成摆设。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
