vcpkg 工程手册：把 C/C++ 依赖恢复成可审查的二进制图
同一个 C++ 仓库，在开发机上能找到 fmt，到了 CI 却重新编译半小时；Windows 产物可以链接，交叉编译时却把宿主机工具当成目标库；升级一个 baseline 后，几十个包同时变化，却没人能解释到底改了什么。表面上这些都是“依赖安装失败”，实质上混在一起的是四类事实：项目声明了什么依赖、端口从哪里解析、依赖为哪个目标环境构建，以及二进制缓存是否与当前构建身份一致。
vcpkg 解决的是 C/C++ 依赖获取、构建和消费问题，不替代 CMake、MSBuild、Ninja 或编译器。架构师真正要建立的也不是一条 vcpkg install 命令，而是一条可重建、可审查、可回滚的依赖链。
先把 classic mode 和 manifest mode 分开
classic mode 把已安装包放在某个 vcpkg 实例下，适合临时实验和人工探索：
vcpkg install fmt
vcpkg list这种状态不随业务仓库版本化。另一台机器只拿到源码，并不知道应该安装哪些 feature、使用什么 baseline，也无法仅凭提交恢复同一依赖图。
manifest mode 把依赖意图放进项目根目录的 vcpkg.json，安装树默认落在项目侧的 vcpkg_installed。依赖变更可以进入代码评审，CI 也能从仓库事实恢复环境。Microsoft 的版本机制说明还明确了一个关键边界：版本选择能力只对 manifest mode 生效。
新项目应优先采用 manifest mode。classic mode 可以保留为诊断入口，但不要把某台共享构建机的全局安装状态当成项目契约。
安装入口要能回答“这次用了哪份端口树”
vcpkg 常见入口是克隆官方仓库并执行 bootstrap。Windows 与 POSIX 环境分别使用对应脚本：
git clone https://github.com/microsoft/vcpkg.git C:\tools\vcpkg
Set-Location C:\tools\vcpkg
.\bootstrap-vcpkg.bat -disableMetrics
.\vcpkg.exe version
git rev-parse HEADgit clone https://github.com/microsoft/vcpkg.git "$HOME/tools/vcpkg"
cd "$HOME/tools/vcpkg"
./bootstrap-vcpkg.sh -disableMetrics
./vcpkg version
git rev-parse HEAD官方的 CMake 快速开始给出了 clone、bootstrap、manifest 和 CMake 接入的完整入口。企业环境不能只记录 vcpkg version：vcpkg 可执行文件、内置 registry 的 Git 提交、项目 baseline 和自定义 registry 都会影响结果。至少保留：
vcpkg version
git -C "$VCPKG_ROOT" rev-parse HEAD把 VCPKG_ROOT 写进开发机环境或 CI 变量可以稳定入口，但不要把个人绝对路径提交进 CMake preset。更稳妥的做法是由开发容器、工具安装脚本或 CI setup 步骤提供路径，再由 preset 引用环境变量。
离线安装不能只复制一个 vcpkg 二进制。端口定义可能继续下载上游源码、补丁和构建工具；真正的离线基线还需要固定端口树、准备 asset cache、准备 binary cache，并在断网环境做一次冷启动验证。
用 manifest 跑通最小依赖闭环
在可删除目录创建最小项目：
vcpkg-lab/
├─ CMakeLists.txt
├─ CMakePresets.json
├─ vcpkg.json
└─ src/
└─ main.cppvcpkg.json 只声明业务真正使用的依赖：
{
"name": "vcpkg-lab",
"version-string": "1.0.0",
"builtin-baseline": "<approved-vcpkg-commit>",
"dependencies": [
"fmt"
]
}baseline 不是装饰字段。它把内置 registry 的版本视图固定到一个已知提交。初次建立或受控更新时使用：
vcpkg x-update-baseline --add-initial-baseline
vcpkg x-update-baseline不要在日常构建中自动更新 baseline。更新会改变整个版本视图，应作为独立依赖升级提交，评审 manifest、baseline、构建日志、许可证和测试差异。
最小程序：
#include <fmt/core.h>
int main() {
fmt::print("vcpkg-model-ok\n");
}CMakeLists.txt 使用包导出的 target，而不是手写 include 和 library 路径：
cmake_minimum_required(VERSION 3.25)
project(vcpkg_lab LANGUAGES CXX)
find_package(fmt CONFIG REQUIRED)
add_executable(vcpkg-lab src/main.cpp)
target_compile_features(vcpkg-lab PRIVATE cxx_std_17)
target_link_libraries(vcpkg-lab PRIVATE fmt::fmt)项目 preset 在第一次 project() 前提供 vcpkg toolchain：
{
"version": 6,
"configurePresets": [
{
"name": "dev",
"generator": "Ninja",
"binaryDir": "${sourceDir}/build/dev",
"cacheVariables": {
"CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
"VCPKG_TARGET_TRIPLET": "x64-windows"
}
}
]
}Linux 或 macOS 应改为团队批准的 triplet，不要照抄 Windows 值。运行：
cmake --preset dev
cmake --build build/dev --parallel
./build/dev/vcpkg-lab预期不只是程序输出。配置日志应显示 vcpkg 恢复依赖，find_package 得到 fmt::fmt，构建树使用预期编译器和 triplet。需要追查 CMake 集成变量时查 vcpkg CMake integration。
manifest、baseline 和版本约束怎样共同解析
manifest 描述直接依赖和 feature；registry 提供可用端口版本；baseline 给每个端口一个版本起点；version>= 只表达最低要求；overrides 才会强制指定版本。vcpkg 的版本解析不是“自动选择最高版本”，官方版本参考说明它会在满足约束时选择最低可用版本。
{
"name": "gateway-native",
"version-semver": "2.3.0",
"builtin-baseline": "<approved-vcpkg-commit>",
"dependencies": [
{ "name": "curl", "features": ["ssl"] },
{ "name": "zlib", "version>=": "1.3.1" },
"fmt"
],
"overrides": [
{ "name": "fmt", "version": "11.0.2" }
]
}overrides 会压过其他版本约束，适合短期处理冲突或安全修复，但也会隐藏传递依赖期待。每个 override 都应有原因、owner、删除条件和回归测试，不能成为永久补丁抽屉。
端口版本中的 #N 表示打包定义的修订，不等于上游库发布了新版本。看到 1.2.3#4 时，要同时审查上游版本和 port recipe 的变化。
feature 是增量能力，不是互斥产品档位
依赖 feature 会改变传递依赖和二进制身份：
{
"dependencies": [
{
"name": "curl",
"default-features": false,
"features": ["ssl"]
}
]
}feature 应表达可叠加能力。官方的 feature 概念说明不建议用 feature 表达互斥后端，因为启用一个 feature 不应让另一个失效。项目关闭默认 feature 时，要验证传递依赖、编译定义和运行时能力，不能只看安装成功。
可以用以下命令观察图，而不是猜测：
vcpkg depend-info
vcpkg install --dry-run
vcpkg list升级 feature 后至少做 clean configure、完整构建、测试和产物依赖检查。缓存命中不代表新 feature 真的进入了链接结果。
triplet 决定的远不止 CPU 名称
triplet 描述目标环境组合，包括架构、操作系统、编译器约束、C/C++ runtime、静态或动态链接策略等。同一个库的 x64-windows 与 x64-windows-static 不是可随意互换的下载变体，而是两种二进制身份。
vcpkg help triplet
vcpkg install --triplet x64-linux社区 triplet 没有与内置稳定 triplet 相同的持续验证承诺。使用前应阅读 triplet 说明，把编译器、runtime、链接方式和支持平台纳入团队支持组合。
自定义 triplet 放到仓库受控目录，不修改 vcpkg 安装目录：
build/
└─ vcpkg-triplets/
└─ x64-linux-company.cmakeset(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)通过 vcpkg-configuration.json、CLI 或 CMake 变量声明 overlay triplet。triplet 改动会使二进制身份变化，应触发缓存隔离和全量回归，而不是复用旧 build tree。
交叉编译必须分清 host 和 target
代码生成器、协议编译器等工具需要在构建机运行，业务库则要为目标设备生成。两者不能使用同一 triplet。manifest 中的 host dependency 会先按 host triplet 构建：
{
"dependencies": [
{ "name": "company-codegen", "host": true },
"company-runtime"
]
}调用时显式记录两侧：
vcpkg install \
--triplet arm64-linux-company \
--host-triplet x64-linux宿主工具和目标库的处理方式可从 host dependencies核对。交叉编译故障先检查工具到底在哪台机器运行，再检查库为哪个 ABI 构建；不要看到 file not found 就直接添加搜索路径。
registry 与 overlay 的职责不能混用
自定义 registry 适合长期维护的私有端口集合，有版本数据库、baseline 和团队发布流程。vcpkg 支持 built-in、Git 和 filesystem registry，项目通过 vcpkg-configuration.json 选择来源：
{
"default-registry": {
"kind": "builtin",
"baseline": "<approved-vcpkg-commit>"
},
"registries": [
{
"kind": "git",
"repository": "https://example.invalid/vcpkg-registry.git",
"baseline": "<approved-registry-commit>",
"packages": ["company-*"]
}
]
}示例域名不可直接用于生产。真实 registry 地址应通过仓库配置表达，认证交给 Git credential helper 或 CI 身份，不把 token 拼进 URL。远程认证行为可查 vcpkg authentication。
overlay port 的优先级高于 registry 解析，适合开发尚未发布的端口或验证补丁：
vcpkg install --overlay-ports=build/vcpkg-ports正因为优先级高，overlay 也能悄悄替换正式端口。长期补丁应进入受控 registry；临时 overlay 要有来源、diff、测试、退出条件，并在 CI 打印生效路径。包名解析规则列出了 registry、overlay port 和 overlay triplet 的解析优先级。
asset cache 与 binary cache 解决两种不同成本
asset cache 保存上游源码归档和构建工具下载，解决公网不可达、上游消失和离线恢复；binary cache 保存某个依赖在特定构建身份下的产物，解决重复编译成本。二者不能互相替代。
本地 binary cache 可以先用文件系统验证：
$env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite"
vcpkg installexport VCPKG_BINARY_SOURCES="clear;files,/var/cache/vcpkg,readwrite"
vcpkg install远程缓存需要最小权限：普通 PR 只读，受保护分支或专门构建任务才允许写入。官方 binary caching说明缓存包包含构建输出、集成文件、使用说明和许可证等内容。把写权限开放给不受信任流水线，等于允许它向后续构建提供可执行二进制。
asset cache 的配置入口是 X_VCPKG_ASSET_SOURCES。离线环境还应启用阻断源站的策略，并在隔离网络中验证没有回退公网。具体语法与排障入口在 asset cache 教程。
缓存治理至少记录命中率、下载量、构建时长、存储增长、保留期、写入主体和清理责任。故障时先用只读或 clear 基线重跑，判断是解析、源码资产还是二进制缓存污染。
代理、证书与凭证要沿下载链逐段定位
vcpkg 可能通过 Git 拉 registry，通过 HTTP 下载源码，通过 NuGet 或其他后端访问 binary cache。设置一个代理变量不代表三条链都会生效。排查时逐段确认：
git config --show-origin --get-regexp 'http\..*proxy|http\..*sslCAInfo'
vcpkg install --debug
cmake --version企业 CA 应通过操作系统、Git、代理或批准的证书文件注入，不关闭 TLS 校验。CI 日志不得打印带密码的 URL、授权头、credential helper 输出和完整环境变量。
凭证应按 registry 只读、缓存只读、缓存写入等职责分离，并设置过期与撤销路径。开发者个人令牌不应成为共享 CI 的长期依赖。
CI 需要同时验证冷恢复和热缓存
只跑热缓存会掩盖上游资产缺失、错误认证和不完整端口；只跑冷缓存则无法发现缓存键污染和成本失控。可以把流水线分成两类：
日常 PR 使用只读 binary cache，执行 configure、build、test，并记录命中情况。定时或升级任务从空安装树、空 build tree 和受控 asset cache 恢复一次完整依赖图。
CI 日志应保留 vcpkg 提交、manifest 与配置 diff、host/target triplet、编译器身份、缓存源类型和失败端口。不要上传包含凭证的完整环境快照。
缓存键不能只包含 vcpkg.json 哈希。编译器、triplet、端口 recipe、feature、baseline、环境透传和工具链都会改变二进制身份。优先让 vcpkg 自身判断 ABI，而不是自制一个过粗的 CI 缓存键覆盖整个 vcpkg_installed。
常见失败要按证据链止血
find_package 找不到已经安装的包
先确认配置阶段是否使用 vcpkg toolchain、toolchain 是否在第一次 project() 前生效、当前 build tree 是否缓存过另一套配置：
cmake -S . -B build/trace --debug-find
cmake -LAH -N build/trace不要先手写 include 路径。那会绕过 imported target 的编译定义、传递依赖和 Debug/Release 位置。
同一 manifest 在两台机器生成不同结果
比较 baseline、registry 提交、triplet、编译器、feature、环境变量和 overlay 生效路径。只有 manifest 相同远远不够。
缓存命中后出现链接或运行时错误
记录缓存命中的包，清空项目安装树并临时禁用远程缓存重建。如果冷构建成功，继续审查缓存写权限、ABI 身份和污染时间段；不要把“再 clean 一次”当成根治。
更新 baseline 后大面积失败
先回滚 baseline 提交恢复交付，再按端口变更分组升级。一次升级中不要同时修改编译器、triplet、registry 和业务源码，否则失败归因会失去边界。
升级与回滚要保留整组输入
一次可回滚升级应把下面事实放在同一评审单元：
vcpkg 工具提交或安装版本。built-in 与自定义 registry baseline。vcpkg.json、vcpkg-configuration.json 和 overlay diff。
host/target triplet、编译器与 CMake preset。依赖图、许可证、安全扫描、构建与测试证据。binary cache 命名空间或只读切换方案。
回滚不能只改回 vcpkg.json。如果新 baseline 已向共享缓存写入产物，还要隔离新缓存写入，并确认旧工具链能从旧基线重新恢复。
端口脚本、Registry 与缓存都是供应链输入
端口 recipe 会下载源码、应用补丁并执行构建逻辑；registry、overlay 和 asset mirror 都是代码或输入供应链。团队要评审端口来源、提交签名或固定哈希、补丁内容、许可证和维护责任。x-block-origin 之类的离线阻断只有在实际隔离演练中才算有效。
二进制缓存写权限尤其敏感。任何能写缓存的身份，都可能影响后续开发机和 CI 取得的可执行产物。受信任构建任务应使用短期身份，普通分支只读，缓存异常时能够按命名空间或时间窗口隔离。
跨平台支持不能只写“Windows、Linux、macOS 都支持”。应明确每个平台的编译器、runtime、triplet、动态库部署方式和代表性测试。社区 triplet、私有 port 和交叉编译组合需要单独 owner，不能借用公共 registry 的质量承诺。
长期维护还要控制存储与构建成本：记录端口平均构建时长、缓存命中率、缓存体积、失效频率和上游下载可用性。命中率低时先查 ABI 输入是否漂移，不要简单扩大缓存保留期。
项目使用 manifest mode，依赖、feature、baseline 和 registry 配置进入版本控制。vcpkg 工具来源、端口树提交、编译器、host/target triplet 和 CMake preset 可追踪。classic mode 只用于临时诊断，不作为共享项目状态。
自定义 registry 用于长期端口治理，overlay 只用于有退出条件的局部开发。asset cache 与 binary cache 分开设计，并做断网冷恢复和热缓存验证。registry、缓存和镜像凭证按读写职责拆分，日志不泄露地址与密钥。
CI 同时验证干净恢复、构建、测试、缓存命中和失败证据。baseline、triplet、feature 或工具链升级有独立变更、停止条件和整组回滚路径。端口 recipe、补丁、许可证、二进制来源和缓存写入身份纳入供应链审查。