🚀 从零开始：高效使用 Vcpkg 安装 Qt WebEngine（经典模式 · 缓存优化 · 性能释放）

🧩 背景简介

在使用 Vcpkg 安装 Qt 系列库时，特别是庞大的 qtwebengine 模块，编译量极大，耗时可达数十小时，若系统未优化或未启用缓存机制，还会重复编译同样的包，浪费时间与性能。

本文将从零开始介绍如何：

1. 安装与配置 Vcpkg（经典模式）
2. 最大化释放编译性能
3. 启用并验证缓存机制
4. 实现可迁移的构建环境（跨机不重编）

---

1️⃣ 安装 Vcpkg（经典模式）

✅ 下载 Vcpkg 源码

推荐将 Vcpkg 放在非系统盘，例如：

git clone https://github.com/microsoft/vcpkg E:\Dev\vcpkg

✅ 初始化并构建可执行文件

cd E:\Dev\vcpkg
.\bootstrap-vcpkg.bat

你会获得：

E:\Dev\vcpkg\vcpkg.exe

此时你就可以使用经典模式（非清单）的方式来安装包：

vcpkg install qtwebengine:x64-windows

不需要 vcpkg-configuration.json 文件，适合需要多个项目共用 Qt、避免重复安装的场景。

---

2️⃣ 设置环境变量（统一路径 & 缓存支持）

启动脚本可以参考 PowerShell 终端环境自动化配置

✅ 推荐统一使用环境变量（加入 PowerShell 启动脚本）

编辑文件（如 C:\Users\<你>\.powershell\env.ps1）：

# ========== Vcpkg 环境变量 ==========
$vcpkgRoot = $env:VCPKG_ROOT
if (-not $vcpkgRoot -or -not (Test-Path "$vcpkgRoot\vcpkg.exe")) {$vcpkgRoot = "E:\Dev\vcpkg"
}# 检查是否存在 vcpkg.exe
if (Test-Path "$vcpkgRoot\vcpkg.exe") {# 设置缓存目录$vcpkgCache = "$vcpkgRoot\archives"Set-Item -Path "Env:VCPKG_ROOT" -Value $vcpkgRootSet-Item -Path "Env:VCPKG_BINARY_SOURCES" -Value "clear;files,$vcpkgCache"Write-Host "✅ VCPKG_ROOT 设置为 $vcpkgRoot"Write-Host "✅ VCPKG_BINARY_SOURCES 设置为 clear;files,$vcpkgCache"
} else {Write-Warning "⚠️ 未找到 Vcpkg 路径：$vcpkgRoot（请检查路径或修改默认值）"
}

作用：

• clear：该命令会清除 vcpkg 当前的二进制缓存。具体来说，它会删除存储在 vcpkg 缓存目录（如 archives）中的所有预编译二进制包。这意味着下次安装时，vcpkg 会重新下载和编译所需的包。

例子：

当您设置如下环境变量时：

Set-Item -Path "Env:VCPKG_BINARY_SOURCES" -Value "clear;files,$vcpkgCache"

• clear 会清除当前的二进制缓存。
• files,$vcpkgCache 指定了您希望 vcpkg 使用的本地缓存路径（$vcpkgCache）。

使用场景：

• 清除缓存：当您遇到缓存问题或包无法正确安装时，使用 clear 可以帮助解决问题。
• 保留本地缓存：您可能会清理缓存后，仍然希望从本地路径加载包。这时，files 就会指定本地缓存路径，避免每次都从网络下载。

注意：

清除缓存会导致下次安装时需要重新下载和编译，可能会稍微延长安装时间。如果您不希望清除缓存，只需去掉 clear，如：

Set-Item -Path "Env:VCPKG_BINARY_SOURCES" -Value "files,$vcpkgCache"

📦 启动 PowerShell 确认环境变量：

$env:VCPKG_BINARY_SOURCES
# 输出应为：clear;files;E:\Dev\vcpkg\archives

---

3️⃣ 开启性能最大化构建环境

默认 Windows 系统会限制后台构建工具（如 ninja.exe、cl.exe）的 CPU 使用率，尤其在节能或平衡模式下，仅能发挥 20~30% 性能。

✅ 步骤 1：调整系统电源策略

• 打开：设置 → 系统 → 电源和电池
• 将电源模式设置为：最佳性能
• 如果为笔记本，请确保已接通电源再构建

✅ 步骤 2：编译工具使用多线程（仅当手动构建）

cmake --build . --config Release -- -j12

但 Vcpkg 默认已自动启用最大并行 ninja -j N，性能会立即体现。

---

4️⃣ 安装 Qt WebEngine 模块

✅ 直接安装命令（经典模式）：

vcpkg install qtwebengine:x64-windows

此过程将：

• 下载源码依赖（如 Chromium、PDFium）
• 启动 CMake 配置
• 调用 ninja 构建 Debug / Release 双版本
• 安装产物到 installed/x64-windows 和 installed/x64-windows/debug

📍 注意事项

• 你可能会看到 ninja.exe 占用 80~100% CPU，这是正常现象（如果电源设置对了）；

• 构建过程中 CPU 多核、内存占用高、硬盘写入频繁，属于高强度构建流程；

• 编译日志可查看：

  buildtrees/qtwebengine/install-x64-windows-rel-out.log
  buildtrees/qtwebengine/install-x64-windows-dbg-out.log
  

---

5️⃣ 缓存机制详解 & 启用验证

✅ 缓存目录结构（例）：

E:\Dev\vcpkg\archives\
└── 0a\└── 0a78d8ce9245...qtwebengine_x64-windows_abcdef.zip

这些 .zip 文件就是构建成功后的二进制缓存，供未来复用。

✅ 如何确认缓存命中？

可用 --dry-run 测试是否命中缓存：：

vcpkg install qtwebengine:x64-windows --dry-run

输出中若有：

Restored 1 package(s) from E:\Dev\vcpkg\archives

说明命中成功。

若没有命中，会触发重新编译。原因可能包括：

• portfile 变动（Vcpkg 仓库更新）
• baseline 更新（git 拉新）
• triplet 或 feature 改变
• 环境变量没设置正确

---

6️⃣ 跨机迁移方案（不再重新编译 Qt）

✅ 拷贝以下两个目录：

E:\Dev\vcpkg\               ← 主目录（含 installed/, ports/, buildtrees/）
E:\Dev\vcpkg\archives\      ← 缓存目录（.zip 包）

✅ 新机器恢复步骤：

# 1. 解压 vcpkg 到同路径
# 2. 设置环境变量（推荐加入 env.ps1）
# 3. 可选：git checkout <旧版本 commit> 固定 ports 内容
# 4. 启动 PowerShell 运行 vcpkg install
#    → 将自动命中缓存，无需重新编译

---

📌 附：如何固定版本防止被更新

cd E:\Dev\vcpkg
git log -1 --oneline
# f7b89fa3 Update qtwebengine to 6.8.3git checkout f7b89fa3
.\bootstrap-vcpkg.bat

这样你构建时使用的 Qt/WebEngine 版本不会发生变化，缓存也能正确命中。

---

✅ 总结

目标	状态
使用经典模式安装 Qt	✅ 已完成
启用缓存并集中管理	✅ 缓存目录为 E:\Dev\vcpkg\archives
释放系统性能编译加速	✅ 设置为“最佳性能”电源计划，已启用多线程
日志可追踪构建进度	✅ buildtrees/qtwebengine/*.log
可迁移构建环境复用	✅ 打包 vcpkg 目录和缓存 zip 即可
防止版本变动触发重编	✅ 固定 Vcpkg 仓库 Git 提交

是的，clear 确实会清除 vcpkg 中之前的缓存。

作用：

• clear：该命令会清除 vcpkg 当前的二进制缓存。具体来说，它会删除存储在 vcpkg 缓存目录（如 archives）中的所有预编译二进制包。这意味着下次安装时，vcpkg 会重新下载和编译所需的包。

例子：

当您设置如下环境变量时：

Set-Item -Path "Env:VCPKG_BINARY_SOURCES" -Value "clear;files,$vcpkgCache"

• clear 会清除当前的二进制缓存。
• files,$vcpkgCache 指定了您希望 vcpkg 使用的本地缓存路径（$vcpkgCache）。

使用场景：

• 清除缓存：当您遇到缓存问题或包无法正确安装时，使用 clear 可以帮助解决问题。
• 保留本地缓存：您可能会清理缓存后，仍然希望从本地路径加载包。这时，files 就会指定本地缓存路径，避免每次都从网络下载。

注意：

清除缓存会导致下次安装时需要重新下载和编译，可能会稍微延长安装时间。如果您不希望清除缓存，只需去掉 clear，如：

Set-Item -Path "Env:VCPKG_BINARY_SOURCES" -Value "files,$vcpkgCache"

总结：

• clear 会清除缓存，是一个有用的选项来解决缓存相关的问题，但也会导致需要重新下载和编译依赖包。
• 使用 files,$vcpkgCache 使 vcpkg 从指定的本地路径加载缓存。

如果您有其他问题或需要进一步解释，请随时告诉我！