Windows下编译vlc-qt全指南：Qt与libVLC SDK版本匹配实战

简介：面向需要在 Windows 平台编译 VLC-Qt 的 C++ 开发者，这份最新资源打包了 vlc-3.0.0-win64 基础运行库、vlc-qt-1.1.1 源码以及作者在 Windows 下预先编译好的 debug 与 release 版本库。拿到后既可以直接链接库文件快速集成播放功能，也可以对照源码研究 VLC-Qt 的构建细节，省去自行下载依赖、配置环境和反复编译的繁琐过程，尤其适合视频播放器开发、音视频处理以及 Qt 控件集成场景。整个压缩包共 77 个文件，大小约 36.71MB；组成上包括 38 个头文件与 8 个 lib 导入库，用于工程引用和链接；10 个 dll 负责运行期动态加载；17 个 cmake 文件可平滑接入 CMake 构建体系；另有 qmldir、qmltypes 等 QML 集成描述文件，方便在 Qt Quick 项目中使用 VLC-Qt 控件，并保留原始基础库压缩包便于核对。资源按 include、lib、bin、cmake 等目录清晰组织，目前已有 1914 人学习下载。对于想在 Windows 上使用 VLC-Qt 或排查其编译问题的开发者，这是一份可以直接对照使用的完整参考。 在 Windows 下编译 vlc-qt，最麻烦的其实不是 CMake 命令本身，而是把 Qt、libVLC SDK、编译器这三样东西的“口味”对到一起。vlc-qt 是对 libVLC 做的 Qt 风格 C++ 封装，让 Qt 程序不需要直接操作 C 语言那一堆libvlc_media_player_t指针，就能用信号槽的方式把播放器“嵌”进界面里。适合想在 Qt 项目里快速接入本地视频、网络流、低延迟播放的 C++ 开发者。

这篇文章我直接按最新版本的踩坑过程来写：基于 Qt 5.15.2（LTS）、VLC 3.0.20 的官方开发包、CMake 3.20 以上的组合，分别在 MinGW 和 MSVC 两条工具链下跑通编译。如果你也在 Windows 上卡过vlccore路径、libvlc.dll.a找不到、或者 Qt 版本和编译器位数对不上这一类问题，这篇应该能帮你省掉一个下午。

1. 先搞清楚：vlc-qt 是个什么项目，为什么 Windows 上这么难搞

1.1 用一句话说清 vlc-qt 的价值

libVLC 本身是个纯 C 接口的库，功能很强，但用起来真的很“原生”：你要手动libvlc_new()创建实例，手动libvlc_media_player_new()创建播放器，还要自己处理事件管理器、自己转回调、自己保证 C 指针的生命周期不出问题。写个简单播放器还行，一旦功能多了，C++ 工程里混着一堆 C 风格代码，维护体验会直线下降。

vlc-qt 做的就是把这一层包起来。项目在 GitHub 上可以直接搜到，核心目录里有VlcMedia.h、VlcMediaPlayer.h、VlcVideoWidget.h这一组类，调用方式基本上就是：

VlcMediaPlayer *player = new VlcMediaPlayer(); VlcMedia *media = new VlcMedia(vlcInstance, "file:///path/to/video.mp4"); player->open(media);

对比裸调 libVLC，代码量少一半，而且播放控件能直接当QWidget塞进布局里，不用自己做窗口句柄绑定。这也是很多 Qt 播放器项目选它的原因。

1.2 Windows 下编译难，难在哪几个点

Linux 上编译 vlc-qt 其实挺省心，apt 装好libvlc-dev基本就能过。但 Windows 下有四个坑是绕不开的：

• libVLC 的 SDK 不会跟着播放器安装包一起给。如果你本机只装了 VLC 播放器，那抱歉，include\vlc、libvlc.lib、libvlccore.lib这些开发文件一个都没有，CMake 配置阶段就会直接失败。
• VLC 官方在 Windows 上提供的 SDK 是用 MinGW 工具链生成的，库文件后缀是.dll.a这种格式，MSVC 环境下链接时会多一层手续，很多人在这里放弃。
• Qt、VLC、编译器三者必须位数一致、确定性一致。64 位的 Qt 配 32 位 VLC，或者 Debug 工程链 Release 的库，都会在生成或链接阶段冒出各种奇奇怪怪的报错。
• vlc-qt 对 Qt6 的支持一直不算完整，最新的稳定路线基本还停在 Qt5。我看到不少新手上来就装 Qt6.5，然后QWidget那边编译报错，第一反应是源码有问题，其实版本匹配没做对。

这三件事想明白了，后面的操作流程就顺了。下面我按工具链选择开始拆。

2. 编译前的选择题：用 MinGW 还是 MSVC，先别急着敲命令

2.1 方案 A：MinGW + Qt Creator，最省心的一条路

如果你只是想把 vlc-qt 编出来，并且后面用 Qt Creator 开发播放器，我强烈建议先走 MinGW 路线。

原因很简单：VLC 官方 Windows 开发包就是用 MinGW 编的，你用同一套工具链去编 vlc-qt，libvlc.dll.a、libvlccore.dll.a直接链接，CMake 识别路径也干脆。这套方案我不需要做任何额外的“格式转换”，全程解压、配置、编译、安装，一条龙下来基本没有物理障碍。

具体组合建议：

• Qt：5.15.2 LTS，安装时选择mingw81_64这一套
• 编译器：跟 Qt 安装包自带的 MinGW 8.1 保持一致，不要自己另装别的 MinGW
• VLC 开发包：3.0.20 win64 版本
• CMake：3.20 以上，带 GUI 也行，命令行更直白

注意：Qt 在线安装器里那个 MinGW 版本和 VLC 官方 SDK 的 GNUC 版本不需要完全一致，但位数必须一致，否则后面链接libvlc.dll.a会直接报格式错误。

2.2 方案 B：MSVC + Visual Studio，给习惯 VS 调试的人准备的

如果你是老 VS 用户，习惯用 MSVC 编译器和 Visual Studio 调试器，那也可以走 MSVC 路线。只是这路线多出来的工作量，主要在 VLC 库的“版本兼容”上。

VLC 官方 SDK 里的导入库.dll.a是 MinGW 格式，MSVC 的link.exe不认。所以要么你用 SDK 自带的头文件 + 运行时的libvlc.dll动态加载，要么自己生成一个.lib导入库。实测下来，用 CMake 的IMPORTED目标去引用.dll.a有时也能含糊过关，但出问题的概率比 MinGW 大不少。

我的意见是：没特殊需求，优先 MinGW。MSVC 方案可以等 MinGW 编译跑通之后，再作为“进阶玩法”去研究。

2.3 版本匹配核对表，先把地基打牢

我整理了一份自用的参考表，编译前对着核一遍，能排除掉六成以上的环境问题：

3. 依赖准备：Qt、libVLC SDK、CMake 三件套怎么配

3.1 安装一个“干净”的 Qt

在线的 Qt 安装器里，勾选Qt 5.15.2下的MinGW 8.1 64-bit那一栏，外加对应的 Qt WebEngine 就够用了。安装时有一点要注意：Qt 安装器允许你同时勾选多个工具链的 Qt 实例，比如msvc2019_64和mingw81_64都打上勾。如果你后续同时搞两个方案，建议装到不同目录，或者至少你要能分清楚CMAKE_PREFIX_PATH里写的是哪一个。

判断当前 Qt 对应哪个编译器，可以在 Qt 的对应套件目录下执行qmake -query，看输出的QMAKE_SPEC字段。如果显示win32-g++，就是 MinGW 套件；如果显示win32-msvc，就是 MSVC 套件。这个字段经常被忽略，但它能解释很多“为什么 CMake 找到了 Qt 却编不过”的问题。

另外提醒一句，Qt 6.x 的版本目前不建议用于 vlc-qt 编译。等项目原作者或社区把 Qt6 的 CMake 支持补全之前，5.15 是稳妥的选择。

3.2 拿一份 libVLC 的开发包，别只用播放器安装包

VLC 官网的下载页里，除了播放器安装包，还有一份“开发包”（通常是vlc-3.0.20-win64.7z这种名字），里面包含：

• include/：一堆.h文件，其中vlc/vlc.h是主入口
• lib/：libvlc.dll.a、libvlccore.dll.a或.lib格式的导入库（不同版本不同）
• bin/：运行时需要的全部 DLL

把开发包整个解压到一个纯净目录，比如D:/dev/vlc-3.0.20-win64，然后把它下面的bin目录加到系统PATH里。这一步很多人会漏，导致编译过了、运行时一启动就报“找不到 libvlc.dll”。

千万不要试图用 VLC 播放器安装目录里的libvlc.dll去充当开发包。它能跑，但没有头文件和导入库，CMake 在 configure 阶段就过不去。用开发包是最省事、最符合编译预期的方式。

3.3 确认 CMake 和构建工具可用

Windows 下最容易被坑的一处是：PATH 里可能同时有好几个 CMake，甚至还有 MSYS2 自带的那套。编译前先在终端里跑一遍：

cmake --version mingw32-make --version

如果你用的是 Qt 自带的 MinGW，mingw32-make在 Qt 安装目录的Tools/mingw810_64/bin下面，可能需要手动把它加进 PATH。CMake 建议直接用独立安装版，不要用 Qt Creator 内置的那个，因为命令行版本更便于排查路径问题。

4. CMake 配置与构建实操：从 clone 到出 lib

4.1 下载源码与目录规划

我通常会把所有东西集中放在一个地方管理，比如：

D:/dev/ vlc-qt/ # 源码目录 vlc-3.0.20-win64/ # VLC 开发包 vlc-qt-build/ # 编译目录 vlc-qt-install/ # 安装目录

源码直接用 Git 拉取，或者下载 zip 包都行。这里强调一下**“源码目录”与“编译目录”分开**，因为 CMake 会把一大堆中间文件散落得到处都是，混在一起后面清理起来特别痛苦。这也是我在多工程协作里养成的习惯，简单但救命。

4.2 MinGW 方案完整编译命令

进入vlc-qt源码目录后，我一般直接这样配置：

cd D:/dev/vlc-qt mkdir build cd build cmake -G "MinGW Makefiles" \ -DCMAKE_PREFIX_PATH=D:/dev/Qt/5.15.2/mingw81_64 \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=D:/dev/vlc-qt-install \ -DVLCCORE_INCLUDE_DIR=D:/dev/vlc-3.0.20-win64/include/vlc \ -DVLCCORE_LIBRARY=D:/dev/vlc-3.0.20-win64/lib/libvlccore.dll.a \ -DVLCLIB_LIBRARY=D:/dev/vlc-3.0.20-win64/lib/libvlc.dll.a \ ..

几个参数逐个解释一下：

• CMAKE_PREFIX_PATH：指向 Qt 的具体套件目录。注意这个路径粒度很重要，不能只写D:/dev/Qt/5.15.2，要写到带编译器后缀的那一层。原因很简单：CMake 是拿它去lib/cmake下面找 Qt5Config.cmake 的，写成多组件共存的那层目录，CMake 会懵掉。
• VLCCORE_INCLUDE_DIR：我写的是include/vlc，不是include。因为 vlc-qt 的 CMakeLists 里查找的是vlc/vlc.h，如果你直接给到include层，它反而找不到。
• VLCCORE_LIBRARY和VLCLIB_LIBRARY：指向lib目录里对应的.dll.a文件。注意 Windows 下 VLC 开发包给的库名是带.dll.a后缀的，这是 MinGW 的导入库格式，别在官网找libvlc.lib。

配置成功后再编译和安装：

mingw32-make -j4 mingw32-make install

-j4是并行任务数，根据你的 CPU 线程数调整。整个编译过程会依次生成VlcCommon、VlcMedia、VlcMediaPlayer、VlcVideoWidget等目标，正常情况下几分钟能跑完。

4.3 MSVC 方案的关键差异

MSVC 方案其实也大同小异，只是生成器换成 VS 工程，路径也不同：

cmake -G "Visual Studio 16 2019" -A x64 \ -DCMAKE_PREFIX_PATH=D:/dev/Qt/5.15.2/msvc2019_64 \ -DCMAKE_INSTALL_PREFIX=D:/dev/vlc-qt-install-msvc \ -DVLCCORE_INCLUDE_DIR=D:/dev/vlc-3.0.20-win64/include/vlc \ -DVLCCORE_LIBRARY=D:/dev/vlc-3.0.20-win64/lib/libvlccore.dll.a \ -DVLCLIB_LIBRARY=D:/dev/vlc-3.0.20-win64/lib/libvlc.dll.a \ ..

MSVC 方案里，libvlc.dll.a这个问题比较扎手。如果你在链接阶段碰到“无法解析的外部符号”，最直接的解决办法是转成.lib导入库，用gendef导符号表，再用lib /def:libvlc.def /out:libvlc.lib /machine:x64生成 MSVC 格式的导入库。拿到libvlc.lib和libvlccore.lib后，再把CMakeCache.txt里的库路径改过去重新 configure。步骤不难，但确实多一道工序，所以我更推荐 MinGW。

构建命令也要换成 CMake 风格：

cmake --build . --config Release cmake --install . --config Release

4.4 install 之后，目录里有什么

安装目录里你会看到：

• include/：vlc-qt 导出的公共头文件
• lib/：vlc-qt.lib或libvlc-qt.dll.a，以及 CMake package 配置文件
• bin/：vlc-qt.dll，运行时必须拷到可执行文件旁边

后面在别的工程里引用时，CMake 会通过lib/cmake下的包配置文件去find_package(vlc-qt)，所以这一步不能省。

5. 联调验证：编译出来的库怎么在 Qt 工程里用起来

5.1 在 CMakeLists 中引入 vlc-qt

假设你要写一个新工程，最简 CMakeLists 长这样：

cmake_minimum_required(VERSION 3.20) project(MyPlayer) set(CMAKE_PREFIX_PATH "D:/dev/Qt/5.15.2/mingw81_64" "D:/dev/vlc-qt-install" # 重点：vlc-qt 的 cmake 配置在这个目录下 ) find_package(Qt5 COMPONENTS Widgets REQUIRED) find_package(vlc-qt REQUIRED) add_executable(MyPlayer main.cpp) target_link_libraries(MyPlayer PRIVATE Qt5::Widgets vlc-qt)

这里最容易踩的坑是CMAKE_PREFIX_PATH里多个路径的写法。Windows 下路径分隔符是分号;，CMake 也认分号，但你在 shell 里传参时可能需要加引号。另外，CMake 默认不会去非标准位置找包，所以 vlc-qt 的安装目录必须写进CMAKE_PREFIX_PATH，或直接指定vlc-qt_DIR。

5.2 一个最小播放器 demo 和运行时 DLL 问题

写一个最小播放器验证库能不能用：

#include <QApplication> #include <VlcMediaPlayer.h> #include <VlcMedia.h> #include <VlcVideoWidget.h> int main(int argc, char *argv[]) { QApplication app(argc, argv); VlcInstance *instance = new VlcInstance(VlcCommon::args(), this); VlcMediaPlayer *player = new VlcMediaPlayer(instance); VlcVideoWidget *videoWidget = new VlcVideoWidget; player->setVideoWidget(videoWidget); VlcMedia *media = new VlcMedia("file:///C:/test.mp4", true, instance); player->open(media); videoWidget->resize(800, 450); videoWidget->show(); player->play(); return app.exec(); }

编译通过只是第一步，运行时大概率会直接报“找不到 vlc-qt.dll”。解决方式有两个：

1. 把D:/dev/vlc-qt-install/bin下的vlc-qt.dll和D:/dev/vlc-3.0.20-win64/bin下的所有 DLL 拷到 exe 同目录。
2. 调试阶段更推荐在 Qt Creator 的运行环境设置里把PATH加上这两个 bin 目录，省得每次拷来拷去。

重点提醒：运行时缺 libVLC 的 DLL 和缺 vlc-qt 的 DLL 是两回事。前者会导致“无法定位程序输入点”，后者会直接“找不到模块”。排查时先把 VLC SDK 的 bin 加进 PATH，再确认 vlc-qt 的 bin 有没有跟上。

5.3 CMake 找不到 vlc-qt 时的排查方向

见过不少人在这一步卡住。常见原因也就这几个：

• CMAKE_PREFIX_PATH没把 vlc-qt 的安装目录写进去，或写的目录层级不对。
• 手动设置了vlc-qt_DIR，但指向的不是lib/cmake/vlc-qt-xxx那一层。
• 工程里已经缓存了旧的 CMakeCache.txt，把上次失败的路径记下来一直用。先在 build 目录里删掉CMakeCache.txt再重新 configure，能解决一半的“迷之找不到”。

这些坑没有多高深，但每一个都确实耗时间。排查时先看 CMake 的FindPackage日志，别急着怀疑代码。

6. 高频问题排查与个人实操心得

6.1 常见错误速查表

6.2 几条很少被写进文档的经验

我前后折腾过好几种组合，最后沉淀下来几条“只可意会不可言传”的经验：

• 先定架构，再定版本。不管用什么工具链，先确定 64 位还是 32 位。Windows 下最容易找不到北的就是一会儿装了 x64 的 VLC，一会儿又装了 x86 的 Qt，到头来都是白费力气。定好 x64，所有依赖全部选 x64。
• 尽量全用 Release，省一半心。VLC 官方 SDK 基本不提供 Debug 版导入库，如果你用 Debug 工程去链接，就算代码能编过，运行时也可能因为 C 运行时库不一致翻车。vlc-qt 项目本身也很少有人用 Debug 配置跑，所以你想“Debug 编译”来打断点的话，大概率要折腾很久。实用做法是 Release 编译 + 日志输出排查。
• 杀毒软件会把编译速度坑成蜗牛。Windows Defender 有时候会对新增的.dll、.exe文件做实时扫描，vlc-qt 编译时会生成不少中间文件，实测把 build 目录加进排除列表之后，编译速度快了接近一倍。
• QML 别指望直接调用这套库。如果你最终想在 QML 里写播放器界面，用 vlc-qt 这套产物是不太行的——它的渲染控件是QWidget生态，不是 QML Item。QML 侧要么再包一层QQuickPaintedItem，要么干脆换别的方案。这个坑我在需求评审阶段经常看到有人踩。

6.3 假如你想从零开始避开所有弯路

把整个流程压缩成一份“闭眼抄”清单，大概是这样：

1. 下载 Qt 5.15.2（MinGW 64 位），安装时勾选对应编译器。
2. 下载 VLC 3.0.20 win64 开发包，解压，把bin加入 PATH。
3. 拉取 vlc-qt 源码目录。
4. 使用cmake -G "MinGW Makefiles"配置，注意把VLCCORE_INCLUDE_DIR指到include/vlc，把两个库路径指到.dll.a文件。
5. mingw32-make然后mingw32-make install。
6. 新工程里find_package(vlc-qt REQUIRED)，运行时把 SDK 的bin和 vlc-qt 的bin都带上。

这套流程能覆盖 Windows 下 90% 的编译需求。如果你后面真的要用 MSVC，那我只能说：先把 MinGW 版跑通、把原理吃透，再碰 VS 工程格式，会轻松很多。

我自己在 Windows 下编译 vlc-qt 翻过最多的车，不是编译报错，而是版本先后完全搞反——先装了最新 Qt6，又装了 32 位 VLC，最后才去看 vlc-qt 的CMakeLists.txt到底要求什么，绕了一大圈。如果只留一条建议给你，那就是：先核对版本匹配表，再动手，比任何技巧都重要。后面等 Qt6 相关的适配更成熟了，我再回来更新一篇新工具链的编译心得。

本文还有配套的精品资源，点击获取