Video2X 在 Windows 上从源码构建指南：基于 CMake、MSVC 与 Vulkan 的完整流程-平芜编程栈

Video2X 在 Windows 上从源码构建指南：基于 CMake、MSVC 与 Vulkan 的完整流程

【免费下载链接】video2xA machine learning-based video super resolution and frame interpolation framework. Est. Hack the Valley II, 2018.项目地址: https://gitcode.com/GitHub_Trending/vi/video2x

本篇指南完整讲解如何在 Windows 平台上从源码构建 Video2X 机器学习视频超分辨率与补帧框架，涵盖 Visual Studio 2022 环境准备、winget 依赖安装、FFmpeg 与 ncnn 的下载解压、CMake 配置参数逐项解析、Release 构建与安装产物说明，并结合仓库 CMakeLists.txt 的源码实现剖析底层依赖与链接关系。读完本篇，你将能够独立在 Windows 上产出可运行的video2x.exe命令行工具与libvideo2x共享库，并能为后续 Qt6 图形界面（GUI）的构建做好准备。

1. 构建前置条件（Prerequisites）

在 Windows 上从源码构建 Video2X 需要手动安装以下两类工具，它们不会由项目自动拉取：

Visual Studio 2022
- 必须勾选工作负载：Desktop development with C++（使用 C++ 的桌面开发）
- 项目使用 C++17 标准编译（见 CMakeLists.txt 中target_compile_features(libvideo2x PRIVATE cxx_std_17)），MSVC 编译器是 Windows 构建的主工具链；构建时也会默认启用/W4 /permissive-等严格警告选项（CMakeLists.txt）
winget-cli（Windows 程序包管理器）
- Windows 10/11 通常自带；若缺失需先安装。后续 CMake、Vulkan SDK 等依赖均通过它安装

补充硬件前提：从源码构建时，CPU 是否支持 AVX2 取决于你选择的编译选项；而运行阶段 Video2X 的 ncnn 推理后端依赖VulkanGPU 加速，因此显卡必须支持 Vulkan（NVIDIA Kepler 及以上、AMD GCN 1.0 及以上、Intel HD Graphics 4000 及以上，详见 README.md 硬件要求章节）。

2. 克隆仓库（Clone the Repository）

Video2X 使用大量第三方子模块（third_party/下的 ncnn、spdlog、boost、librealcugan_ncnn_vulkan、librealesrgan_ncnn_vulkan、librife_ncnn_vulkan 等），因此必须使用--recurse-submodules参数一次性拉取全部子模块：

# 若尚未安装 Git，先通过 winget 安装 winget install -e --id=Git.Git # 克隆仓库（含所有子模块） git clone --recurse-submodules https://gitcode.com/GitHub_Trending/vi/video2x.git cd video2x

克隆完成后，仓库根目录应包含CMakeLists.txt、include/、src/、third_party/、tools/、models/等目录，其中third_party/下已有各依赖的源码或预编译组件（如third_party/ncnn、third_party/spdlog、third_party/boost均为子模块）。

3. 安装依赖（Install Dependencies）

3.1 通过 winget 安装构建工具

# 安装 CMake winget install -e --id=Kitware.CMake # 安装 Vulkan SDK winget install -e --id=KhronosGroup.VulkanSDK

CMake：项目要求最低版本 3.10（CMakeLists.txt），winget 默认安装的最新版远高于此要求；
Vulkan SDK：视频处理管线与 ncnn 推理均在 Vulkan 上执行。CLI 目标通过find_package(Vulkan REQUIRED)链接Vulkan::Vulkan（CMakeLists.txt），因此 Vulkan SDK 是构建video2x可执行文件的硬性依赖。

3.2 下载并解压 FFmpeg 与 ncnn 预编译库

Video2X 在 Windows 上不通过pkg-config查找系统 FFmpeg（该路径仅用于非 Windows 平台，见 CMakeLists.txt），而是直接使用third_party/下解压好的shared（动态库）版本。文档给出的命令如下：

# 手动依赖的版本号 $ffmpegVersion = "7.1" $ncnnVersion = "20240820" # 下载并解压 FFmpeg（7.1 版 full_build shared 包） curl -Lo ffmpeg-shared.zip "<FFmpeg 7.1 full_build-shared 包的下载直链>" Expand-Archive -Path ffmpeg-shared.zip -DestinationPath third_party Rename-Item -Path "third_party/ffmpeg-$ffmpegVersion-full_build-shared" -NewName ffmpeg-shared # 下载并解压 ncnn（20240820 版，面向 VS2022 的 shared 包） curl -Lo ncnn-shared.zip "<ncnn 20240820 windows-vs2022-shared 包的下载直链>" Expand-Archive -Path ncnn-shared.zip -DestinationPath third_party Rename-Item -Path "third_party/ncnn-$ncnnVersion-windows-vs2022-shared" -NewName ncnn-shared

说明：上述下载直链指向各上游项目的 Release 发布页，请以版本号为准获取对应资源。解压后务必执行Rename-Item将目录规范为third_party/ffmpeg-shared与third_party/ncnn-shared，因为 CMakeLists.txt 的 Windows 分支硬编码了这两个路径：

FFmpeg：set(ffmpeg_base_path "${PROJECT_SOURCE_DIR}/third_party/ffmpeg-shared")，随后链接include/头文件与lib/avcodec.lib、avfilter.lib、avformat.lib、avutil.lib、swscale.lib五个导入库（CMakeLists.txt）；
ncnn：set(ncnn_base_path "${PROJECT_SOURCE_DIR}/third_party/ncnn-shared/x64")，通过add_library(ncnn SHARED IMPORTED)引用bin/ncnn.dll与lib/ncnn.lib，头文件位于include/ncnn（CMakeLists.txt）。

ncnn 的shared 版本必须是面向VS2022构建的（下载包名含windows-vs2022-shared），以保证与 MSVC 工具链的 ABI 兼容。

4. 构建项目（Build the Project）

4.1 CMake 配置命令逐项解析

在仓库根目录执行以下命令进行配置（注意 PowerShell 中使用反引号`作为续行符）：

cmake -S . -B build -DUSE_SYSTEM_NCNN=OFF -DUSE_SYSTEM_SPDLOG=OFF -DUSE_SYSTEM_BOOST=OFF ` -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=build/libvideo2x-shared

各参数含义如下：

参数	值	作用
`-S .`	仓库根目录	指定源码目录
`-B build`	`build/`	指定构建输出目录
`-DUSE_SYSTEM_NCNN=OFF`	OFF	不使用系统 ncnn，转而使用`third_party/ncnn-shared`预编译库；该变量同时作为默认值透传给`third_party/librealesrgan_ncnn_vulkan/src`、`librealcugan_ncnn_vulkan/src`、`librife_ncnn_vulkan/src`三个子项目（见`option(USE_SYSTEM_NCNN "" ${VIDEO2X_USE_EXTERNAL_NCNN})`，CMakeLists.txt）
`-DUSE_SYSTEM_SPDLOG=OFF`	OFF	不使用系统 spdlog，改用仓库`third_party/spdlog`源码（此时会强制`SPDLOG_NO_EXCEPTIONS=ON`，因为 spdlog 异常与 ncnn 不兼容，CMakeLists.txt）
`-DUSE_SYSTEM_BOOST=OFF`	OFF	不使用系统 Boost，改用`third_party/boost`子模块（仅构建`program_options`组件，供 CLI 参数解析使用）
`-DCMAKE_BUILD_TYPE=Release`	Release	选择 Release 构建类型。CMakeLists 会在未显式指定时默认设为 Release（CMakeLists.txt），并对 MSVC 启用`/Ox /Ot /GL`及`/LTCG /OPT:REF /OPT:ICF`优化与链接期代码生成（CMakeLists.txt）
`-DCMAKE_INSTALL_PREFIX=build/libvideo2x-shared`	构建产物目录	指定`install`目标的安装前缀，决定最终产物存放位置

需要说明的是，主项目自身的VIDEO2X_USE_EXTERNAL_NCNN / VIDEO2X_USE_EXTERNAL_SPDLOG / VIDEO2X_USE_EXTERNAL_BOOST三个选项默认均为ON（CMakeLists.txt），即默认走find_package(ncnn)、find_package(spdlog)、find_package(Boost)的查找路径。若你的环境中 find_package 找不到对应库导致配置失败，可显式追加对应开关，例如-DVIDEO2X_USE_EXTERNAL_NCNN=OFF强制走third_party/ncnn-shared预编译库分支。从当前构建命令的组合看，这正是文档所推荐的、不依赖系统安装这些库的构建方式。

4.2 编译并安装

cmake --build build --config Release --parallel --target install

--config Release：多配置生成器（MSVC 的 Visual Studio 生成器）下必须显式指定配置；
--parallel：启用并行编译，可显著缩短构建时间；
--target install：编译完成后执行安装步骤，将产物写入CMAKE_INSTALL_PREFIX指定的目录。

整个构建过程会依次完成：由src/下 13 个.cpp源文件（含libvideo2x.cpp、decoder.cpp、encoder.cpp、filter_realcugan.cpp、filter_realesrgan.cpp、filter_libplacebo.cpp、interpolator_rife.cpp等，见 CMakeLists.txt）编译libvideo2x共享库，链接 FFmpeg、ncnn、spdlog，再编译tools/video2x/src/下的 CLI 入口video2x.cpp并链接libvideo2x与Vulkan::Vulkan、Boost::program_options（CMakeLists.txt）。

5. 构建产物与安装内容

构建完成后，全部产物位于build/libvideo2x-shared目录下，主要包括：

产物	说明
`video2x.exe`	命令行界面（CLI）主程序，通过 video2x.cpp 编译，提供超分辨率、补帧等完整命令参数
`libvideo2x.dll`/`libvideo2x.lib`	`libvideo2x`共享库及其导入库。库的导出 API 由 libvideo2x.h 声明（`VideoProcessor`类，支持`process()`、`pause()`、`resume()`、`abort()`及状态/进度查询）
`include/libvideo2x/*.h`	全部公共头文件，含构建时由 version.h.in 生成的`version.h`（通过`configure_file`将`@PROJECT_VERSION@`替换为项目版本号，CMakeLists.txt）
`lib/cmake/Video2X/`	CMake 包配置文件`Video2XConfig.cmake`（模板见 Video2XConfig.cmake.in）与`Video2XTargets.cmake`，便于其他项目通过`find_package(Video2X)`集成`libvideo2x`
`share/models/`	模型文件目录。Windows 平台下`models/`（Anime4K GLSL、Real-CUGAN、Real-ESRGAN、RIFE 各版本模型）整体安装到`CMAKE_INSTALL_DATADIR`（CMakeLists.txt）
FFmpeg 全部 DLL	安装规则通过`file(GLOB ffmpeg_dlls "${ffmpeg_base_path}/bin/*.dll")`将 FFmpeg 运行时 DLL 一并拷贝到安装目录的 bin 位置，保证程序开箱即跑（CMakeLists.txt）
`ncnn.dll`	若未使用外部 Boost 分支，`ncnn.dll`也会被一并安装到 bin 目录（CMakeLists.txt）

安装规则同时会将libvideo2x目标导出为Video2X::Video2X命名空间下的 CMake target，方便下游项目链接。

6. 构建验证与后续步骤

6.1 快速验证

构建完成后，可在 PowerShell 中运行以下命令检查 CLI 是否可执行：

.\build\libvideo2x-shared\video2x.exe --help

若需进行实际转码，可参考仓库文档命令行使用指南，将输入视频、输出路径、处理器类型（如realesrgan、realcugan、rife、libplacebo）与模型路径正确传入。

6.2 对接 Qt6 GUI

Video2X 还提供 Qt6 图形界面（独立于本仓库的video2x-qt6项目）。根据 Windows (Qt6) 构建指南，构建 GUI 前必须先完成本仓库libvideo2x共享库的构建，并将build/libvideo2x-shared中的产物拷贝到 GUI 项目的third_party/libvideo2x-shared目录，GUI 构建时同样需要third_party/ffmpeg-shared的 FFmpeg 依赖。

6.3 常见问题排查（基于源码结构推断）

find_package(ncnn/spdlog/Boost) 失败：说明系统环境中未安装对应库。按文档推荐将USE_SYSTEM_NCNN/SPDLOG/BOOST设为OFF，必要时显式追加-DVIDEO2X_USE_EXTERNAL_NCNN=OFF等主项目开关，强制使用third_party/下预编译库或子模块源码；
链接报错C2589（min/max 宏冲突）：Windows 下项目已为三个 ncnn-Vulkan 子项目定义了NOMINMAX以规避 MSVC 宏冲突（CMakeLists.txt），一般无需额外处理；
找不到ffmpeg-shared/ncnn-shared目录：检查第 3.2 节的解压与Rename-Item是否执行成功，目录名必须与 CMakeLists 硬编码路径完全一致；
运行时缺少 DLL：确保build/libvideo2x-shared的 bin 目录中包含 FFmpeg DLL 与ncnn.dll，或将它们加入系统PATH。

7. 与其他平台的构建对照

若你同时在 Linux 上构建，可参考 Linux 构建指南：Linux 平台通过pkg-config查找系统 FFmpeg（libavcodec、libavfilter、libavformat、libavutil、libswscale），ncnn 则默认从third_party/ncnn源码构建（仅启用视频处理所需的算子层，如卷积、池化、插值等，其余算子全部关闭以减小体积，见 CMakeLists.txt）。Windows 与 Linux 在依赖获取方式上的差异，本质上由 CMakeLists.txt 中的if(WIN32) ... else() ...分支决定——这也解释了为何 Windows 构建需要手动放置ffmpeg-shared与ncnn-shared两个预编译目录。

至此，你已完整掌握 Video2X 在 Windows 上的源码构建全流程：环境准备 → 克隆子模块 → 安装 CMake/Vulkan SDK → 放置 FFmpeg/ncnn 预编译库 → CMake 配置与并行编译 → 安装产物验证。构建出的libvideo2x共享库与video2x.exe将直接服务于后续的模型推理与 GUI 集成。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考