简介本资源面向在 Windows 平台进行 VLC-Qt 二次开发与音视频播放器集成的开发者提供从依赖库到编译产物的完整环境解决自行编译 VLC-Qt 时依赖缺失、版本不匹配、Debug 与 Release 库混用等常见问题。包内共 77 个文件以 38 个 h 头文件、17 个 cmake 配置脚本、10 个 dll 动态库、8 个 lib 导入库为主另含 vlc-3.0.0-win64.7z 与 vlc-qt-1.1.1.tar.gz 两个源码/运行时压缩包整体约 36.71MB。其中头文件与 cmake 脚本便于在 Qt 工程中直接引用与查找依赖dll 与 lib 则覆盖 VLCQtCore、VLCQtWidgets、VLCQtQml 等模块的调试与发布版本可直接链接使用。目前已有 1917 人学习下载适合需要快速搭建 VLC-Qt 开发环境、对照编译产物排查链接错误的中高级 Qt 开发者参考。1. Windows 下编译 vlc-qt为什么源码编译是绕不开的一步在 Windows 上做 Qt 视频播放器vlc-qt 几乎是绕不开的选择。它把 libvlc 的 C 接口封装成 Qt 风格的类VlcInstance、VlcMediaPlayer、VlcWidgetVideo这套 API 用起来比裸调 libvlc 舒服太多。但真正动手的人很快会发现一个问题官方提供的预编译包往往只对应特定版本的 Qt 和编译器MSVC 2019 配 Qt 5.15 能用换成 MinGW 或者 Qt 6 就直接链接失败。这时候唯一的出路就是自己编译。编译 vlc-qt 这件事说难不难说简单也绝不简单。它依赖 libvlc 的头文件和库、CMake 的版本要够新、Qt 的套件要匹配、生成器要选对。任何一个环节出问题报错信息都不会直接告诉你根因。这篇内容面向的是已经在 Windows 上写过 Qt 程序、现在需要把 vlc-qt 跑起来的开发者。我会把从环境准备到 CMake 配置、从编译到验证的完整路径拆开讲包括我踩过的那些坑。读完你应该能在一个干净的 Windows 环境里从零编译出一套可用的 vlc-qt 库并知道每个参数为什么这么设。2. 编译前的环境准备版本匹配比什么都重要2.1 三个核心依赖的版本关系vlc-qt 的编译依赖三样东西Qt、libvlc、CMake。这三者的版本关系决定了你能不能编译成功以及编译出来的库能不能用。Qt 方面vlc-qt 对 Qt 5 的支持最成熟。Qt 5.15 是长期支持版本社区里用这个版本编译 vlc-qt 的案例最多。Qt 6 虽然 vlc-qt 的新版本有适配但在 Windows 上遇到的兼容问题明显更多尤其是QPainter相关的渲染接口变动。如果你不是非用 Qt 6 不可建议直接上 Qt 5.15。libvlc 方面需要下载 VLC 的 Windows 开发包。注意不是装一个 VLC 播放器就行而是要拿到sdk目录下的头文件和.lib文件。VLC 官网提供的vlc-3.0.x-win64.7z或者vlc-3.0.x-win32.7z里面就包含sdk文件夹。版本上VLC 3.0.x 是当前最稳定的选择4.0 还在开发阶段接口有变动不建议在生产环境用。CMake 方面最低要求是 3.10 以上但我建议直接用 3.20 以上的版本。低版本 CMake 在处理 Qt 的AUTOMOC、AUTOUIC时偶尔会出玄学问题升级到新版能省掉很多莫名其妙的报错。依赖项推荐版本最低版本备注Qt5.15.25.9MSVC 或 MinGW 均可libvlc SDK3.0.203.0.x需完整 sdk 目录CMake3.243.10建议 3.20编译器MSVC 2019MSVC 2017MinGW 也可但坑更多2.2 获取 vlc-qt 源码与目录规划vlc-qt 的源码托管在 GitHub 上直接 clone 或者下载 zip 包都行。我习惯用 git clone方便切换分支和查看提交记录。git clone https://github.com/vlc-qt/vlc-qt.git cd vlc-qt git checkout masterclone 下来之后先别急着编译。我建议在磁盘上建一个清晰的工作目录把依赖和源码分开存放后面 CMake 配置的时候路径不容易搞混。比如D:\dev\ ├── vlc-qt\ # 源码 ├── vlc-sdk\ # 解压后的 VLC SDK │ ├── include\ │ └── lib\ ├── qt\ # Qt 安装目录 └── build\ # 编译输出目录这个结构不是必须的但路径清晰能减少很多「找不到头文件」的低级错误。特别是当你的机器上装了多个版本的 Qt 或者多个版本的 VLC 时路径混乱是编译失败的头号原因。2.3 环境变量与命令行工具确认在 Windows 上编译我强烈建议用x64 Native Tools Command Prompt for VS 2019或者x64 Native Tools Command Prompt for VS 2022来操作。这个命令行工具会自动设置好 MSVC 的cl.exe、link.exe以及相关的环境变量。如果你直接用普通的 cmd 或者 PowerShell需要手动调vcvarsall.bat容易漏掉。打开对应的命令行工具后先验证几个关键命令是否可用cl cmake --version qmake --versioncl会输出 Microsoft 编译器的版本信息cmake --version显示 CMake 版本qmake --version显示 Qt 版本。三个都正常输出说明基础环境没问题。如果qmake找不到需要把 Qt 的bin目录加到PATH里或者直接用 Qt 自带的命令行工具。注意Qt 的bin目录和 MSVC 的bin目录必须在PATH里且 Qt 的优先级要高于其他可能冲突的路径。如果机器上同时装了 MinGW 和 MSVC 两套 Qt务必确认当前用的是哪一套。3. 用 CMake 配置 vlc-qt参数怎么设、报错怎么看3.1 CMake 配置命令的完整写法环境准备好之后进入编译环节。我一般会在源码目录外面建一个build目录做 out-of-source 编译这样源码目录不会被中间文件污染出问题重新来也方便。mkdir build cd build cmake .. ^ -G Visual Studio 16 2019 ^ -A x64 ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_PREFIX_PATHD:/dev/qt/5.15.2/msvc2019_64 ^ -DLIBVLC_INCLUDE_DIRD:/dev/vlc-sdk/include ^ -DLIBVLC_LIBRARYD:/dev/vlc-sdk/lib/libvlc.lib ^ -DLIBVLCCORE_LIBRARYD:/dev/vlc-sdk/lib/libvlccore.lib ^ -DBUILD_TESTSOFF这条命令里的每个参数都有讲究。-G指定生成器Visual Studio 16 2019对应 VS 2019如果你用 VS 2022 就改成Visual Studio 17 2022。-A x64指定目标架构是 64 位这个必须和你的 Qt 版本、VLC SDK 版本一致。CMAKE_BUILD_TYPE在 VS 生成器下其实不生效因为 VS 是多配置生成器但写上没坏处用 Ninja 或者 Makefile 生成器时就有用了。CMAKE_PREFIX_PATH指向 Qt 的安装目录CMake 会从这里找Qt5CoreConfig.cmake等配置文件。LIBVLC_INCLUDE_DIR指向 VLC SDK 的include目录LIBVLC_LIBRARY和LIBVLCCORE_LIBRARY分别指向libvlc.lib和libvlccore.lib。这两个库文件缺一不可libvlc.lib是核心播放接口libvlccore.lib是底层依赖。3.2 配置阶段的常见报错与排查CMake 配置阶段最常见的报错是找不到 Qt5。报错信息通常是Could not find a package configuration file provided by Qt5Core。这时候先检查CMAKE_PREFIX_PATH是否指向了正确的 Qt 目录注意路径要用正斜杠或者双反斜杠单反斜杠在 CMake 里会被当成转义字符。另一个高频报错是找不到 libvlc 的头文件。如果 CMake 提示LIBVLC_INCLUDE_DIR无效先确认D:/dev/vlc-sdk/include下面确实有vlc/vlc.h这个文件。VLC SDK 解压后头文件在sdk/include/vlc/下面所以LIBVLC_INCLUDE_DIR应该指向sdk/include而不是sdk/include/vlc。这个路径多一层少一层都会导致编译时找不到vlc.h。还有一种情况是 CMake 找到了 Qt 但版本不对。比如你机器上有 Qt 5.12 和 Qt 5.15 两个版本CMake 默认可能找到旧的那个。这时候可以在CMAKE_PREFIX_PATH里明确指定版本路径或者在 CMake 命令里加-DQt5_DIRD:/dev/qt/5.15.2/msvc2019_64/lib/cmake/Qt5来强制指定。配置成功后CMake 会输出一段总结信息列出找到的 Qt 版本、libvlc 路径、编译选项等。仔细看这段输出确认没有NOT FOUND的条目。如果有说明某个依赖没找到需要回头检查路径。3.3 编译与安装生成库文件和头文件配置通过后就可以执行编译了。用 VS 生成器的话可以直接用cmake --build命令cmake --build . --config Release --target install--config Release指定编译 Release 版本--target install会在编译完成后自动执行安装步骤把头文件、库文件、CMake 配置文件复制到CMAKE_INSTALL_PREFIX指定的目录。默认的安装路径是C:\Program Files\vlc-qt我一般会改成项目目录下的install文件夹方便管理cmake .. ^ -G Visual Studio 16 2019 ^ -A x64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/vlc-qt-install ^ ...其他参数...编译过程大概需要几分钟取决于机器性能。编译完成后install目录下会出现include、lib、bin三个文件夹。include里是 vlc-qt 的头文件lib里是.lib导入库bin里是.dll动态库。如果你要做静态链接需要在 CMake 配置时加-DBUILD_SHARED_LIBSOFF但静态链接 vlc-qt 会复杂不少涉及 libvlc 的静态库和一堆系统依赖新手建议先用动态库跑通。提示编译完成后bin目录下的 DLL 需要和你的应用程序一起发布。如果运行时提示缺少vlc-qt.dll或者libvlc.dll把对应的 DLL 复制到 exe 同级目录即可。4. 避坑指南编译 vlc-qt 时最容易翻车的五个地方4.1 坑一Qt 版本与编译器不匹配现象CMake 配置通过但编译时大量报错提示QWidget: No such file or directory或者链接时找不到 Qt 库的符号。原因Qt 安装目录选错了。比如你用的是 MSVC 2019 编译器但CMAKE_PREFIX_PATH指向了 MinGW 版本的 Qt。MSVC 和 MinGW 编译出来的库 ABI 不兼容混用必然失败。解决确认 Qt 安装目录下的编译器标识。MSVC 版本的 Qt 目录名通常带msvc2019_64MinGW 版本带mingw81_64。用qmake --version查看当前 Qt 的编译器信息确保和命令行环境里的cl编译器一致。4.2 坑二libvlc 库文件缺失或路径错误现象编译通过但链接阶段报unresolved external symbol符号名里带libvlc_前缀。原因LIBVLC_LIBRARY或LIBVLCCORE_LIBRARY指向的.lib文件不对或者只指定了其中一个。vlc-qt 同时依赖libvlc.lib和libvlccore.lib缺一个都会导致链接失败。解决检查 VLC SDK 的lib目录确认libvlc.lib和libvlccore.lib都存在。如果只有.dll没有.lib说明下载的不是开发包需要重新下载带sdk的完整包。另外注意 32 位和 64 位不能混用libvlc.lib的架构必须和 Qt、编译器一致。4.3 坑三CMake 生成器选错导致编译失败现象cmake --build执行时报MSB8020或者The build tools for v142 cannot be found。原因CMake 生成器指定的 VS 版本和实际安装的 VS 版本不匹配。比如指定了Visual Studio 16 2019但机器上只装了 VS 2022。解决用cmake --help查看当前 CMake 支持的生成器列表选择机器上实际安装的 VS 版本对应的生成器。VS 2019 对应Visual Studio 16 2019VS 2022 对应Visual Studio 17 2022。如果不确定可以用Ninja生成器但需要额外安装 Ninja 并配置好 MSVC 环境。4.4 坑四运行时找不到 libvlc.dll现象编译出来的程序能启动但一调用VlcInstance就崩溃或者提示Cannot load libvlc.dll。原因libvlc.dll和libvlccore.dll没有放到可执行文件能找到的路径下。Windows 加载 DLL 的顺序是exe 同级目录 → 系统目录 →PATH环境变量。VLC 安装目录下的 DLL 不在默认搜索路径里。解决把 VLC 安装目录下的libvlc.dll、libvlccore.dll以及plugins文件夹一起复制到你的 exe 同级目录。plugins文件夹里是解码器、渲染器等插件缺少它 libvlc 初始化会失败。注意plugins目录的结构要保持完整不能只复制几个文件。4.5 坑五Debug 版本编译通过但 Release 版本报错现象Debug 配置下编译正常切换到 Release 后出现链接错误或者运行时崩溃。原因Debug 和 Release 的运行时库不同/MDdvs/MD如果 vlc-qt 编译时用的配置和你的应用程序不一致就会出现内存管理冲突。另外Release 下编译器优化可能暴露一些未定义行为。解决确保 vlc-qt 和你的应用程序使用相同的构建配置。如果应用程序是 Releasevlc-qt 也要编译 Release 版本。在 CMake 配置时明确指定CMAKE_BUILD_TYPERelease或者用 VS 生成器时在cmake --build命令里加--config Release。不要混用 Debug 和 Release 的库文件。5. 验证编译结果写一个最小播放器跑通全流程5.1 创建测试工程与 CMakeLists.txt编译出来的 vlc-qt 到底能不能用写一个最小播放器验证一下最直接。新建一个 Qt Widgets 项目在CMakeLists.txt里引入 vlc-qtcmake_minimum_required(VERSION 3.16) project(VlcQtTest LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) find_package(Qt5 REQUIRED COMPONENTS Core Widgets) find_package(VlcQt REQUIRED COMPONENTS Core Widgets) add_executable(VlcQtTest main.cpp) target_link_libraries(VlcQtTest Qt5::Core Qt5::Widgets VlcQt::Core VlcQt::Widgets )find_package(VlcQt REQUIRED COMPONENTS Core Widgets)这行依赖 vlc-qt 安装时生成的VlcQtConfig.cmake文件。如果 CMake 找不到这个文件需要把 vlc-qt 的安装路径加到CMAKE_PREFIX_PATH里或者手动指定VlcQt_DIR。5.2 最小播放器代码与参数说明main.cpp里写一个最简单的播放器加载本地视频文件并播放#include QApplication #include VlcInstance.h #include VlcMediaPlayer.h #include VlcWidgetVideo.h #include VlcMedia.h int main(int argc, char *argv[]) { QApplication app(argc, argv); // 创建 VLC 实例传入必要的参数 VlcInstance *instance new VlcInstance( VlcCommon::args() --no-video-title-show, app ); // 创建视频渲染窗口 VlcWidgetVideo *videoWidget new VlcWidgetVideo(); videoWidget-resize(800, 600); videoWidget-show(); // 创建播放器并绑定视频窗口 VlcMediaPlayer *player new VlcMediaPlayer(instance); player-setVideoWidget(videoWidget); // 加载媒体文件 VlcMedia *media new VlcMedia( D:/test-video.mp4, true, instance ); player-open(media); player-play(); return app.exec(); }VlcCommon::args()返回一组默认的 libvlc 启动参数--no-video-title-show是额外追加的作用是播放时不显示文件名叠加层。VlcMedia的构造函数第三个参数是VlcInstance指针第二个参数true表示本地文件。player-setVideoWidget(videoWidget)把视频输出绑定到 Qt 的窗口控件上这一步是 vlc-qt 封装的核心价值省去了手动处理 HWND 的麻烦。5.3 运行验证与 DLL 部署清单编译这个测试工程之前确保CMakeLists.txt里的VlcQt_DIR指向正确的安装路径。编译成功后把需要的 DLL 复制到 exe 同级目录DLL 文件来源作用vlc-qt.dllvlc-qt 编译输出 bin 目录vlc-qt 核心库libvlc.dllVLC 安装目录libvlc 核心libvlccore.dllVLC 安装目录libvlc 底层核心plugins 文件夹VLC 安装目录解码器与渲染插件运行 exe如果视频窗口正常显示并播放说明整条链路都通了。如果窗口黑屏但没崩溃检查plugins目录是否完整特别是plugins/video_output和plugins/codec这两个子目录。如果程序启动就崩溃用 Dependency Walker 或者dumpbin /dependents检查 DLL 依赖是否齐全。提示测试用的视频文件路径不要带中文和空格libvlc 在某些版本下对非 ASCII 路径处理有问题。先用纯英文路径跑通再测试中文路径。本文还有配套的精品资源点击获取
