Windows 下 VS2022 编译运行 Khronos Vulkan Samples 全避坑指南

KhronosGroup 官方的 Vulkan-Samples 是学习 Vulkan 最佳的实战宝库。但由于它依赖项众多（GLFW, GLM, SPRIV-Cross 等），且对环境配置有要求，很多初学者在第一步编译时就因为各种报错劝退。本文将手把手带你配置这套环境。

第一部分：环境准备（由虚到实）

在下载代码前，必须确保你的"地基"是牢固的。

1. Visual Studio 2022 安装细节

下载：去微软官网下载 Community（社区版）即可。
重点配置 ：在安装界面的"工作负载"页，必须勾选 使用 C++ 的桌面开发 (Desktop development with C++)。
右侧细节 ：确保右侧安装列表中包含了 MSVC ... x64/x86 生成工具 和 Windows 10 (或 11) SDK。

2. Vulkan SDK (显卡开发的灵魂)

下载：LunarG Vulkan SDK。
安装：一路 Next。
验证：打开 CMD，输入 vulkaninfo。如果看到大量显卡信息输出，说明安装成功。
- 博主提示 ：安装后建议重启电脑，确保环境变量 VULKAN_SDK 生效。

3. Python 3 (构建脚本依赖)

Vulkan Samples 内部使用 Python 脚本来转换资源（Shader 编译等）。
关键点 ：安装时务必勾选底部的小框 "Add Python to PATH"。

4. CMake (项目构建工具)

虽然 VS2022 自带 CMake，但为了避免版本兼容问题，建议单独安装最新版 CMake。Download CMake

第二部分：下载源码（最容易翻车的一步）

1. 克隆代码

很多新手下载 ZIP 包，结果编译时提示找不到 glm/glm.hpp 或 glfw，这是因为 ZIP 包不包含 子模块（Submodules）。前提条件：git自带git大文件存储（git-lfs）。Git - Install，Installing Git Large File Storage - GitHub Docs

请使用 Git 命令下载：

复制代码

# 找一个纯英文路径的文件夹，例如 D:\Dev
cd /d D:\Dev

# 核心参数 --recurse-submodules 会自动把数十个依赖库全部拉下来
git clone --recurse-submodules https://github.com/KhronosGroup/Vulkan-Samples.git

2. 检查资产 (Assets)

下载完成后，打开 Vulkan-Samples/assets 文件夹。

正常情况 ：你应该能看到 models, textures 等文件夹，里面有大量文件。
异常情况：如果里面是空的，说明子模块下载失败。

补救措施：

复制代码

cd Vulkan-Samples
git submodule update --init --recursive

第三部分：生成工程 (推荐使用 CMake GUI)

虽然命令行很快，但用 CMake GUI 界面更直观，写博客截图也更清晰。

打开 CMake (cmake-gui)。
Where is the source code : 选择你刚下载的 Vulkan-Samples 文件夹。
Where to build the binaries : 在 Vulkan-Samples 下新建一个文件夹叫 build，选择这个目录。
点击 Configure 按钮：
- 弹出窗口中，Generator 选择 Visual Studio 17 2022。
- Optional platform 选择 x64。
- 点击 Finish。
等待下方出现 "Configuring done"。如果出现红色条目通常是配置项（这是正常的），只要没有报错（Error），再次点击 Configure 直到红色消失。
点击 Generate 按钮。
点击 Open Project，它会自动打开 Visual Studio 2022。

第四部分：编译与运行

1. 编译 (Build)

VS 打开后，顶部工具栏将 Debug 改为 Release（Release 运行帧率高，适合看效果；想断点调试代码选 Debug）。
在右侧"解决方案资源管理器"中，右键点击 Solution 'vulkan_samples' (解决方案)，选择 "生成解决方案" (Build Solution) 。
等待时间：首次编译需要编译 Shader 和大量依赖库，可能需要 5-10 分钟。

2. 设置启动项

编译成功后，在左侧列表中找到 vulkan_samples 项目（通常在 app 文件夹下）。
右键 -> 设为启动项目 (Set as Startup Project)。这一步不做，按 F5 会报错。

3. 运行特定示例

直接按 F5 运行，会弹出一个漂亮的 GUI 界面，列出所有 Sample，你可以点击进入。

高阶技巧：如何在 VS 中直接调试某个特定 Sample？

如果你想一启动就直接运行"Hello Triangle"而不是去选单里找：

右键 vulkan_samples 项目 -> 属性 (Properties)。
选择 调试 (Debugging)。
在 命令参数 (Command Arguments) 中输入：sample hello_triangle。
点击确定，再按 F5，程序就会直接进入三角形演示。

第五部分：常见报错排查 (Troubleshooting)

Q1: 报错 Cannot open include file: 'GLFW/glfw3.h'

原因：下载代码时没加 --recurse-submodules，或者网络不好导致子模块没下全。
解法：执行 git submodule update --init --recursive。

Q2: 报错 Could not find Vulkan

原因：电脑没装 Vulkan SDK 或者装完没重启。
解法：重装 SDK 并重启。

Q3: 运行闪退或提示找不到 assets

原因：VS 的"工作目录"不对。
解法：在 VS 项目属性 -> 调试 -> 工作目录 (Working Directory) ，确保它指向的是包含 assets 文件夹的根目录（通常是 $(ProjectDir)..\..\.. 或手动指定到 D:\Dev\Vulkan-Samples）。注意：默认生成的 CMake 工程通常会自动设置好这个，但如果手动搬运过 exe 就会出错。

Q4: 编译时出现 min 或 max 宏定义冲突

现象：error C2589: '(': illegal token on right side of '::'
原因：Windows.h 定义了 min/max 宏，干扰了 C++ 标准库。
解法：CMake 配置通常已经处理了，如果还遇到，可以在 CMake 预处理器定义中添加 NOMINMAX。