企业官网建设流程全解析

在 Windows 上从源码构建 Video2X Qt6 图形界面：完整编译与部署指南

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

本文以 Video2X 官方构建文档 docs/book/src/building/windows-qt6.md 为骨架，完整讲解在 Windows 上从源码编译 Video2X Qt6 图形界面（GUI）的每一步：环境准备、克隆仓库、预构建libvideo2x共享库、获取 FFmpeg 运行库、使用 Qt Creator 构建，以及用windeployqt部署运行时依赖并成功启动video2x-qt6.exe。读完本文，你将能够在一台干净的 Windows 机器上独立复现整个构建链路，并理解每一步背后的构建系统原理（以仓库根目录 CMakeLists.txt 中的实现为准）。

一、构建前须知：Video2X 6.x 的组件构成

Video2X 6.0.0 起项目被完全重写为 C/C++ 实现（见 README.md）。在 6.x 架构下，项目被拆分为多个可独立构建的组件：

• libvideo2x：核心 C/C++ 处理库，负责视频解码、滤镜（超分辨率）、帧插值与编码，封装了 FFmpeg、ncnn（Vulkan）、Real-ESRGAN、Real-CUGAN、RIFE 等能力；
• video2x CLI：命令行前端，源码位于 tools/video2x/src/video2x.cpp；
• Video2X Qt6 GUI：图形界面前端，由独立的video2x-qt6仓库维护，通过链接libvideo2x共享库工作。

也就是说，Qt6 GUI 并不是一个完全独立的程序，它本质上是libvideo2x的一个图形化调用端。因此构建 GUI 前，必须先把libvideo2x编译成共享库（DLL），这正是本文第 3 节要解决的问题。

二、环境准备（Prerequisites）

官方构建文档假设 Qt6 已安装到默认位置C:\Qt，以下工具需要预先手动安装：

此外，结合 README.md 中列出的硬件要求，你的机器还需满足：

• CPU：预编译二进制要求支持 AVX2（Intel Haswell 及更新、AMD Excavator 及更新）；从源码构建时同样建议选择带 AVX2 指令集的 CPU；
• GPU：必须支持 Vulkan（NVIDIA Kepler/GTX 600 系列及以上、AMD GCN 1.0/Radeon HD 7000 系列及以上、Intel HD Graphics 4000 及以上），因为 ncnn 推理与 libplacebo 渲染均走 Vulkan 硬件管线。

提示：构建仅需要 MSVC 工具链 + CMake + Qt6，Vulkan SDK 在构建 GUI 时并非必需项（CLI 的构建才显式find_package(Vulkan)，见下文源码分析），但运行超分辨率/插值功能时必须有可用的 Vulkan 驱动。

三、克隆仓库

首先用 winget 安装 Git（如尚未安装）：

winget install -e --id=Git.Git

然后克隆video2x-qt6仓库。务必使用--recurse-submodules参数，因为该项目通过 Git 子模块托管了大量第三方依赖（ncnn、spdlog、Boost 以及 Real-ESRGAN/Real-CUGAN/RIFE 的 ncnn-Vulkan 封装库，对应本仓库中的 third_party/ 目录结构），缺少该参数会导致依赖缺失、构建失败：

git clone --recurse-submodules <video2x-qt6 仓库地址> cd video2x-qt6

克隆完成后，进入仓库目录，接下来需要为 GUI 准备其运行所依赖的库。

四、准备依赖一：先构建 libvideo2x 共享库

Qt6 GUI 编译时需要libvideo2x的头文件与导入库（.lib），运行时需要其 DLL。官方构建文档明确要求：在构建 GUI 之前，先把 libvideo2x 构建为共享库，并将产物放到third_party/libvideo2x-shared目录。

libvideo2x的构建方式记录在 docs/book/src/building/windows.md 中，其给出的核心命令如下（在video2x主仓库根目录执行）：

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 cmake --build build --config Release --parallel --target install

理解这条命令，需要对照 CMakeLists.txt 中的实际构建逻辑：

• 共享库开关：BUILD_SHARED_LIBS默认即为ON（CMakeLists.txt），libvideo2x默认以动态库形式产出；
• 依赖开关：顶层实际使用的选项名是VIDEO2X_USE_EXTERNAL_NCNN / VIDEO2X_USE_EXTERNAL_SPDLOG / VIDEO2X_USE_EXTERNAL_BOOST（CMakeLists.txt），三者默认均为ON，即优先使用系统提供的第三方库；上面的命令将其关闭，改为使用third_party下随子模块引入的源码（ncnn、spdlog、Boost）在本地构建，适合不想额外安装系统级依赖的场景；
• FFmpeg 的处理：在 Windows 上，libvideo2x直接从third_party/ffmpeg-shared目录链接avcodec、avfilter、avformat、avutil、swscale五个库（CMakeLists.txt），这正是下一步要手动下载 FFmpeg 共享包并重命名目录的原因；
• 模型文件安装：install规则会把 models/ 下的全部模型（Anime4K GLSL 着色器、Real-ESRGAN/Real-CUGAN/RIFE 的.param/.bin文件）一并安装到数据目录（CMakeLists.txt），确保运行时能加载对应算法。

命令执行完毕后，libvideo2x的头文件、导入库与 DLL 会集中出现在build/libvideo2x-shared下。将整个目录内容复制到 GUI 仓库的third_party/libvideo2x-shared（目录不存在则新建），即完成 GUI 对核心库的依赖准备。

五、准备依赖二：获取 FFmpeg 共享运行库

libvideo2x的解码、编码与像素格式转换全部依赖 FFmpeg，Windows 上以共享库（DLL）形式链接。构建文档给出的获取方式是下载 FFmpeg 官方 Windows 共享构建包（full build shared 版本，由 GyanD 维护发布），版本号以变量形式管理以便升级：

# Versions of manually installed dependencies $ffmpegVersion = "7.1" # Download and extract FFmpeg 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

注意最后一步：解压后必须把目录重命名为ffmpeg-shared。这是因为 CMakeLists.txt 中硬编码了third_party/ffmpeg-shared作为 FFmpeg 查找基准路径，其下的include/（头文件）与lib/*.lib（导入库）会被用于编译链接。如果你使用其他版本（如 7.0、7.1 之后的版本），只需修改$ffmpegVersion变量并保持目录重命名规则一致即可。

下载时请选择shared（共享）构建而非 static（静态）构建，因为构建脚本按共享库方式链接并依赖 DLL 运行。

六、在 Qt Creator 中构建 GUI 项目

依赖准备就绪后，进入构建阶段，官方文档给出的流程极简但有效：

1. 打开项目：在 Qt Creator 中，选择“打开项目”（Open Project），将 GUI 仓库根目录下的CMakeLists.txt文件作为项目文件打开。Qt Creator 会自动读取 CMake 配置并提示选择构建套件（Kit）；
2. 选择正确的 Kit：务必选择与安装的 Qt 版本匹配的MSVC 2022 64-bit套件（例如Desktop Qt 6.8.0 MSVC2022 64bit），否则会因编译器/Qt 架构不匹配而配置失败；
3. 执行构建：点击窗口左下角的锤子图标（Build）即可开始编译。CMake 会先重新生成配置，再调用 MSVC 编译器编译 GUI 源码并链接libvideo2x与 Qt6 库；
4. 产物位置：构建完成后，可执行文件位于build目录下，典型路径形如build\Desktop_Qt_6_8_0_MSVC2022_64bit-Release\video2x-qt6.exe（该路径同时被后续部署命令引用，需保持一致）。

从源码结构看，GUI 通过 CMake 的target_link_libraries与libvideo2x建立链接关系，因此第 4 节中third_party/libvideo2x-shared目录的完备性（头文件 + 导入库 + DLL 三者齐备）直接决定此步能否成功。

七、部署运行时依赖并启动应用

video2x-qt6.exe编译成功后并不能直接双击运行，因为它的运行还依赖大量 DLL：Qt6 核心模块（Core、Gui、Widgets 等）、libvideo2x.dll、FFmpeg DLL 以及 ncnn 的 Vulkan 运行时。官方构建文档给出了两条部署步骤。

7.1 清理发布目录

在复制依赖之前，先进入build目录下对应的 Release 子目录（即video2x-qt6.exe所在目录），删除其中除video2x-qt6.exe和.qm文件以外的所有内容。.qm是 Qt 的翻译文件，必须保留——Video2X Qt6 GUI 内置了英语、简体中文、日语、葡萄牙语、法语、德语等多语言支持（见 README.md），删除后界面将失去本地化能力。

7.2 使用 windeployqt 部署 Qt 运行时

windeployqt是 Qt 官方提供的部署工具，会自动分析可执行文件的依赖并拷贝所需的 Qt DLL、插件与翻译文件。官方文档给出的命令（以 Qt 6.8.0 为例）：

C:\Qt\6.8.0\msvc2022_64\bin\windeployqt.exe --release --compiler-runtime .\build\Desktop_Qt_6_8_0_MSVC2022_64bit-Release\video2x-qt6.exe

参数说明：

• --release：按 Release 模式部署（与构建配置一致，避免混入 Debug 运行库）；
• --compiler-runtime：同时拷贝 MSVC 运行时（vcruntime、msvcp等），保证在没有安装 Visual Studio 运行库的机器上也能运行；
• 路径中的Desktop_Qt_6_8_0_MSVC2022_64bit-Release需与你实际构建输出目录一致；若安装的 Qt 版本不同（如 6.7、6.9），请同步修改C:\Qt\<版本>\msvc2022_64\bin前缀。

7.3 部署 libvideo2x 共享库

最后，把第 4 节准备好的third_party/libvideo2x-shared目录内容复制到video2x-qt6.exe所在的发布目录，但需要排除三个项目：

• include目录：头文件仅编译期需要，运行时不需要；
• libvideo2x.lib：导入库仅链接期需要，运行时不需要；
• video2x.exe：这是 CLI 命令行程序，属于另一个前端，GUI 场景下不需要。

需要一并复制的是libvideo2x.dll及其依赖的 FFmpeg DLL、ncnn DLL 等（libvideo2x的 install 规则本身也会把ffmpeg_base_path/bin/*.dll与ncnn.dll拷贝到 bin 目录，见 CMakeLists.txt）。你可以通过 libvideo2x.h 了解该库对外暴露的 C API，进一步确认 GUI 与核心库的交互边界。

7.4 启动验证

完成以上步骤后，双击video2x-qt6.exe即可启动 GUI。若启动失败，优先检查是否缺少某个 DLL（可用进程监控工具或直接观察报错信息），回到 7.2/7.3 补全对应文件。

八、备选路径：直接使用官方安装包

如果你不需要定制源码，只是想快速获得可用的 GUI，则完全不必走上述编译流程。docs/book/src/installing/windows-qt6.md 提供了更简单的方案：直接下载官方发布的安装程序video2x-qt6-windows-amd64-installer.exe，双击运行，跟随向导选择安装目录与是否创建桌面快捷方式，完成后双击桌面快捷方式即可使用。从源码构建更适合需要二次开发、调试或定制构建选项的开发者。

九、常见问题与排查

Q1：Qt Creator 配置时报找不到libvideo2x？检查third_party/libvideo2x-shared目录是否完整存在，且包含头文件、libvideo2x.lib与libvideo2x.dll；确认构建 libvideo2x 时使用的 MSVC 版本与 Qt 套件的 MSVC 版本一致（均为 MSVC 2022 x64）。

Q2：运行提示缺少avcodec-*.dll等 FFmpeg 库？确认 FFmpeg 共享包已正确重命名为third_party/ffmpeg-shared，且其bin目录下的全部 DLL 已随libvideo2x-shared一起复制到发布目录。若仍然缺失，可直接从 FFmpeg 共享包的bin目录手动补拷。

Q3：构建时找不到ncnn相关依赖？--recurse-submodules克隆是否完整。本仓库对应的third_party/ncnn、third_party/librealesrgan_ncnn_vulkan、third_party/librealcugan_ncnn_vulkan、third_party/librife_ncnn_vulkan等子模块缺一不可，缺少时执行git submodule update --init --recursive补齐后重新配置。

Q4：程序启动后无法进行超分辨率/插值处理？确认 GPU 支持 Vulkan 且驱动已更新；libvideo2x的 ncnn 推理路径依赖 Vulkan 设备（对应本仓库中的filter_realcugan、filter_realesrgan、interpolator_rife等实现，见 src/filter_realcugan.cpp 等文件）。

总结

从源码构建 Video2X Qt6 GUI 的本质是一条“先库后壳”的依赖链：先编译libvideo2x共享库并安放至third_party/libvideo2x-shared，再获取 FFmpeg 共享包并重命名为third_party/ffmpeg-shared，随后在 Qt Creator 中以 MSVC 2022 64-bit 套件构建 GUI，最后用windeployqt部署 Qt 运行时、复制 libvideo2x 及 FFmpeg DLL 完成收尾。理解 CMakeLists.txt 中BUILD_SHARED_LIBS、VIDEO2X_USE_EXTERNAL_*等选项的语义与third_party/ffmpeg-shared硬编码路径，能帮助你在版本升级、路径变更等场景下快速定位并解决问题。

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