# Vcpkg 集成

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

为了帮助您管理项目依赖项和外部库，CLion 集成了 [vcpkg](https://vcpkg.io/en/index.html)，这是一个 C/C++ 的包管理器。

> **Note:**
> 当前的限制：
>
>
>
> * 完整的 vcpkg 功能集适用于 [CMake](quick-cmake-tutorial.html) 项目。 对于其他 [项目格式](project-models.html)，仅支持浏览和安装包。
>
> * 支持的工具链包括所有 除外 ，适用于 [Windows Cygwin](quick-tutorial-on-configuring-clion-on-windows.html#Cygwin)、 [WSL](how-to-use-wsl-development-environment-in-product.html)、 [Docker](clion-toolchains-in-docker.html) 和 [Remote](remote-projects-support.html)。
>
>
>
> 请参阅 [已知问题](#known-issues)，了解 CLion 跟踪器中的相关票据。

Procedure: 安装 vcpkg

> **Tip:**
> Vcpkg 将安装到您的系统中。 您可以安装多个 vcpkg 实例，每个实例包含不同的包集合。
>
>
>
> 此外，您可以将多个项目链接到一个 vcpkg 仓库。

1. 从主菜单中选择  `查看 | 工具窗口 | Vcpkg`  以打开   Vcpkg   工具窗口。

2. 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)：

![在 vcpkg 工具窗口中添加 vcpkg 按钮](https://resources.jetbrains.com/help/img/idea/2026.3/cl_add_vcpkg_icon.png)

3. 在   添加 Vcpkg 仓库   对话框中指定安装设置：

![添加 vcpkg 仓库](https://resources.jetbrains.com/help/img/idea/2026.3/cl_add_vcpkg_dialog.png)

* 您的 vcpkg 仓库的 名称 和 URL 。

* 安装目录 （或使用默认值）。 如果您已经安装了 vcpkg，请在此字段中提供其位置的路径。

* 将 vcpkg 集成添加到现有 CMake 配置文件 > **Note:** > 此选项仅适用于 CMake 项目。 CLion 使用 CMake 工具链文件与 vcpkg 集成。 选择您希望工具链文件链接到的 [CMake 配置文件](cmake-profile.html)。 安装完成后，您可以通过 `CMAKE_TOOLCHAIN_FILE` 变量在所选配置文件的 CMake 选项 中找到工具链文件。

4. 点击   确定   并等待安装完成。

包列表将显示在中间窗格中。 在右侧窗格中，您可以找到所选包的描述和操作。

![Vcpkg 工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_toolwindow_installsuccess.png)

> **Tip:**
> 如果 vcpkg 未链接到任何配置，您将看到它显示为灰色。 使用   编辑 vcpkg   对话框（ ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.edit_dark.svg)）将其链接到配置。
>
>
>
> ![Vcpkg 未链接到任何 CMake 配置文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_noprofile.png)

Procedure: 浏览并安装包

> **Note:**
> 选择特定版本的选项尚未实现（ [CPP-32366](https://youtrack.jetbrains.com/issue/CPP-32366/vckpg-Add-ability-to-select-version-of-package)）。 只能安装最新的包版本。

1. 要查找特定包，请在搜索字段中开始输入其名称：

![搜索包](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_search.png)

2. 选择包并按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `⏎` (Xcode), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (ReSharper), `⏎` (ReSharper (macOS)), `Enter` (QtCreator), `⏎` (QtCreator (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)) 或点击右侧窗格中的   安装  。

3. 在经典模式下，如果包安装成功，CLion 将提示您将其添加到  `vcpkg.json`  并切换到清单模式：

![安装通知](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_install_addtojson_notification.png)

4. 您可以在   已安装 | 经典模式   或   已添加 | 清单模式   下找到已安装的包。

> **Note:**
> 经典模式显示仓库中的所有包，而 [清单模式](#switch-manifest) 显示添加到  `vcpkg.json`  的包。

经典模式:

![已安装包的子树](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_installed.png)

清单模式:

![添加到 vcpkg.json 的包](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_installed_manifestmode.png)

Procedure: 切换到清单模式

> **Note:**
> 如果项目根目录下有  `vcpkg.json`  文件，CLion 将自动切换到清单模式。
>
>
>
> 请注意，经典模式和清单模式是互斥的。

1. 点击   切换到清单模式   按钮：

![切换到清单模式](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_switchtomanifest.png)

2. 选择要添加到  `vcpkg.json`  的包：

![将添加到 vcpkg.json 的包](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_switchtomanifest_dialog.png)

3. CLion 将创建一个  `vcpkg.json`  文件，添加包，并将项目切换到清单模式：

![已切换到清单模式](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_manifest_switched.png)

Procedure: 检查控制台输出

控制台：vcpkg   是一个只读选项卡，显示所有 vcpkg 命令及其完整输出。

![Vcpkg 控制台选项卡](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_consletab.png)

> **Tip:**
> 使用上下箭头在命令之间跳转：
>
> ![在控制台选项卡中跳转命令](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_console_jump.png)

* 当发生错误时，例如在安装包期间，CLion 会显示通知消息。 点击   显示输出   打开控制台选项卡并调查问题。

![安装错误消息](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_errormessage.png)

* 在使用 vcpkg 时，您可以随时切换到   控制台   选项卡。 该选项卡也可以通过   显示控制台   按钮访问。

![显示控制台按钮](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_showconsole.png)

Procedure: 安装/移除多个包

1. 在树中选择多个包。

2. 使用以下快捷键：

* 要安装或添加到 `vcpkg.json` ，请按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `⏎` (Xcode), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (ReSharper), `⏎` (ReSharper (macOS)), `Enter` (QtCreator), `⏎` (QtCreator (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。

* 要移除，请按 `Alt+Delete` / `⌘⌫` 。

Procedure: 开始使用包

包应添加到 [CMakeLists.txt](cmakelists-txt-file.html)。 对于大多数包，vcpkg 提供了要包含在 CMake 脚本中的代码。

1. 如果 vcpkg 提供了提示，您将在通知中看到   将软件包添加到 CMakeLists.txt   选项：

![将包添加到 CMakeLists.txt](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_add_cmakelists.png)

2. 将建议的代码复制到您的  `CMakeLists.txt`  文件中。 如果需要，请将目标链接名称（默认为  `main` ）更改为您希望包链接到的名称。

![粘贴到 CMakeLists.txt 的代码](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_add_cmakelists_code.png)

Procedure: 更新 vcpkg 和包

使用以下工具窗口操作进行更新和升级：

* 更新全部   更新 vcpkg Git 仓库到最新版本，然后检查是否有可用的包更新。

![更新全部图标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_updateall_icon.png)

* 升级全部   更新 vcpkg Git 仓库到最新版本，然后将所有已安装的包更新到其最新版本。

![升级全部图标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_upgradeall_icon.png)

* 检查更新  （ ![三点图标](https://resources.jetbrains.com/help/img/idea/2026.3/toolbox-ide-settings-icon.png) 菜单）检查 vcpkg Git 仓库是否有新版本。

* 更新仓库  （ ![三点图标](https://resources.jetbrains.com/help/img/idea/2026.3/toolbox-ide-settings-icon.png) 菜单）检查 vcpkg Git 仓库的当前版本是否有可用的包更新。

* 升级仓库  （ ![三点图标](https://resources.jetbrains.com/help/img/idea/2026.3/toolbox-ide-settings-icon.png) 菜单）检查 vcpkg Git 仓库的当前版本是否有可用的包更新并安装它们。

* 更新 Vcpkg 仓库  （ ![三点图标](https://resources.jetbrains.com/help/img/idea/2026.3/toolbox-ide-settings-icon.png) 菜单）更新 vcpkg Git 仓库到最新版本。

Procedure: 逐个升级包

可以升级的包会用警告标志标出。

* 选择一个包并点击右侧窗格中的   升级软件包   图标：

![逐个升级包](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_updatepackages_onebyone.png)

Procedure: 自动更新仓库

* 点击工具栏上的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.settings.svg) 并选择   IDE 启动时自动更新仓库  ，以允许 CLion 在每次 IDE 启动时检查仓库更新。

![在 IDE 启动时自动更新仓库的选项](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_autoudate_onrestart.png)

Procedure: 使用快速修复添加缺失的包

* 如果您包含了一个尚未安装的包的头文件，编译将失败，并显示  file not found  错误。 点击错误消息旁的   修复  。

![构建错误消息中的快速修复链接](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_quickfix.png)

CLion 将建议安装缺失的包：

![建议快速修复缺失的包](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_quickfix_suggestion.png)

* 如果有多个候选项可供安装，请从   修复   菜单中打开列表：

![修复菜单](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_quickfix_candidates.png)

在对话框中选择要安装的包：

![包候选项对话框](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_quickfix_candidates_dialog.png)

> **Tip:**
> 修复   也适用于未链接到包管理器的配置文件。

Procedure: 强制使用系统 CMake 和 Ninja

您可以 [强制](https://learn.microsoft.com/en-us/vcpkg/users/config-environment#vcpkg_force_system_binaries) vcpkg 使用 [配置](cmake-profile.html) 环境中的 CMake 和 Ninja。

1. 点击左侧窗格中的   编辑 vcpkg   按钮：

![编辑 vcpkg 图标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_editicon.png)

2. 展开   高级设置   部分并设置   使用系统二进制文件   复选框：

![强制使用系统二进制文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_usesysbins.png)

Procedure: 故障排除：vcpkg 安装 x64-windows 三元组而不是 MinGW 三元组

当您在 MinGW 上添加包时，标准 vcpkg 会安装 x64-windows 三元组，而不是 [MinGW 三元组](https://learn.microsoft.com/en-us/vcpkg/users/platforms/mingw#mingw-native)。 CLion 可以自动修复此问题。

1. 点击错误消息中的   修复  。

![MinGW 三元组的修复](https://resources.jetbrains.com/help/img/idea/2026.3/cl_vcpkg_mingw_fix.png)

2. 在经典模式下，CLion 会将  `VCPKG_TARGET_TRIPLET`  添加到当前配置的   CMake 选项  。

在清单模式下，CLion 会将  `VCPKG_TARGET_TRIPLET`  添加到   CMake 选项  ，并附加两个环境变量：  `VCPKG_DEFAULT_TRIPLET`  和  `VCPKG_DEFAULT_HOST_TRIPLET` 。

## 已知问题和限制

* 目前，vcpkg 不支持以下工具链：Cygwin（ [CPP-31665](https://youtrack.jetbrains.com/issue/CPP-31665)）、Remote（ [CPP-30683](https://youtrack.jetbrains.com/issue/CPP-30683)）、Docker（ [CPP-30684](https://youtrack.jetbrains.com/issue/CPP-30684)）和 WSL（ [CPP-30685](https://youtrack.jetbrains.com/issue/CPP-30685)）。

* 编辑器中缺失包的快速修复功能正在开发中（ [CPP-31662](https://youtrack.jetbrains.com/issue/CPP-31662)）。

## See also

### 外部链接

[vcpkg's GitHub page](https://github.com/microsoft/vcpkg)

### 操作指南

[快速 CMake 教程](quick-cmake-tutorial.html) [CMake profiles](cmake-profile.html) [CLion toolchains](how-to-create-toolchain-in-clion.html)

### 流程

[Conan 插件](conan-plugin.html)

