简介本资源面向需要在 Windows 平台使用 Qt 集成 VLC 播放能力的开发者提供 vlc-qt 1.1.1 的完整编译成果与配套源码解决自行编译时依赖配置繁琐、版本匹配困难的问题。包内共 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 脚本便于二次开发与工程集成dll 与 lib 覆盖 debug、release 两种构建模式可直接链接使用。资源已获 1917 人学习下载适合具备一定 Qt 与 C 基础、希望快速搭建视频播放模块的中高级开发者参考能省去从源码编译到环境调试的大量重复工作。1. 为什么在 Windows 上编译 vlc-qt 总翻车一份能跑通的工程笔记在 Windows 上把 vlc-qt 从源码编译出来是很多做 Qt 桌面播放器的工程师绕不开的一关。你可能已经试过直接git clone然后qmake make结果卡在libvlc找不到、vlc.lib链接失败、或者 qmake 报一堆cannot find -lpublic之类的错误。vlc-qt 本质上是 libvlc 的 Qt 封装它把 VLC 的 C 接口包装成 Qt 风格的类让你能在 QWidget 里直接嵌一个视频播放器。问题在于它依赖预编译好的 libvlc 开发包而这个包在 Windows 上的目录结构、库名、头文件路径和 Linux 完全不一样官方文档又写得含糊导致大量时间耗在环境配置上。这篇笔记面向的是需要在 Windows 上落地 vlc-qt 的 Qt 开发者从依赖准备到编译参数、从 CMake 配置到常见报错一步步拆开讲目标是让你照着做能出VlcQtCore.dll和VlcQtWidgets.dll。2. 编译前的依赖准备libvlc 开发包与 Qt 版本怎么选2.1 为什么不能直接用 VLC 安装目录里的库很多人第一反应是装个 VLC 播放器然后去安装目录找libvlc.dll和libvlc.lib直接塞进 vlc-qt 的工程里。这个做法在早期版本偶尔能蒙混过关但在较新的 vlc-qt 上基本会翻车。原因是 VLC 官方安装包里的libvlc.lib是给运行时用的导入库它对应的头文件版本、导出符号和 vlc-qt 源码里引用的 API 不一定对得上。更关键的是vlc-qt 需要的是完整的开发包包含include/vlc/下所有头文件、lib/下的.lib文件、以及plugins/目录缺一不可。常见做法是去 VLC 的官方下载站找win64或win32的7z压缩包文件名类似vlc-3.0.x-win64.7z解压后里面有一个sdk目录那才是编译 vlc-qt 真正需要的东西。注意版本匹配vlc-qt 的 master 分支通常跟进 VLC 3.x如果你拿 VLC 4.x 的 SDK 去编头文件里的函数签名变了编译期就会报一堆未定义符号。2.2 Qt 版本与编译器组合的边界vlc-qt 对 Qt 的要求不算苛刻Qt 5.9 到 Qt 5.15 都能编Qt 6 需要看分支。但编译器必须和 libvlc SDK 的位数一致SDK 是 64 位Qt 就必须用 MSVC 64 位或 MinGW 64 位。我一般推荐 MSVC 2017 或 2019 配合 Qt 5.15原因是 VLC 官方 SDK 就是用 MSVC 编的MinGW 链接 MSVC 生成的.lib虽然有时能过但遇到 C 异常传播或 STL 边界问题时容易出玄学崩溃。下面这张表是我实测过的几组组合供你选型时参考Qt 版本编译器VLC SDK 版本结果Qt 5.15.2MSVC 2019 64bitVLC 3.0.18 win64通过Qt 5.15.2MinGW 8.1 64bitVLC 3.0.18 win64链接警告运行偶发崩溃Qt 5.12.12MSVC 2017 64bitVLC 3.0.16 win64通过Qt 6.2.4MSVC 2019 64bitVLC 3.0.18 win64需切分支master 未完全适配选好之后把 VLC SDK 解压到一个没有空格和中文的路径比如D:\dev\vlc-sdk。路径里有空格是 qmake 和 CMake 的经典坑后面会细说。2.3 获取 vlc-qt 源码与目录结构确认源码直接从 GitHub 上 clone 即可注意要拉子模块因为 vlc-qt 依赖一个叫vlc-qt-common的东西不过新版已经合并进主仓库了。clone 下来之后根目录下应该有src/、tests/、CMakeLists.txt和VlcQt.pro这些文件。如果你只看到CMakeLists.txt没有.pro说明你拉的是较新分支构建方式以 CMake 为主。git clone https://github.com/vlc-qt/vlc-qt.git cd vlc-qt git submodule update --init --recursive这段命令做两件事拉主仓库、初始化子模块。子模块没拉的话编译时会报找不到VlcQtCore的源文件。拉完之后用dir确认一下src/core和src/widgets两个目录存在这是后面要编出两个 DLL 的源头。3. 用 CMake 配置 vlc-qt参数怎么传、路径怎么写3.1 CMake 与 qmake 两条路的选择vlc-qt 同时提供.pro和CMakeLists.txt但我建议在 Windows 上走 CMake。原因是 qmake 在处理 libvlc 的依赖路径时对 Windows 反斜杠和空格的处理很脆弱而 CMake 的find_package和target_link_libraries更可控。尤其是你要把 vlc-qt 集成到自己的 CMake 工程里时CMake 方式能直接add_subdirectory省去手动配.pri文件的麻烦。如果你坚持用 qmake核心是在.pro里指定VLCQT_LIBRARY和VLCQT_INCLUDE_DIR但这两个变量名在不同版本里改过容易对不上。CMake 这边变量名相对稳定下面按 CMake 走。3.2 关键 CMake 变量的含义与传参打开 vlc-qt 根目录的CMakeLists.txt你会看到它依赖几个变量来定位 libvlc。最核心的是LIBVLC_INCLUDE_DIR和LIBVLC_LIBRARY。前者指向 SDK 里的sdk/include后者指向sdk/lib/libvlc.lib和sdk/lib/libvlccore.lib。一个典型的配置命令如下mkdir build cd build cmake .. -G Visual Studio 16 2019 -A x64 ^ -DLIBVLC_INCLUDE_DIRD:/dev/vlc-sdk/sdk/include ^ -DLIBVLC_LIBRARYD:/dev/vlc-sdk/sdk/lib/libvlc.lib ^ -DLIBVLC_CORE_LIBRARYD:/dev/vlc-sdk/sdk/lib/libvlccore.lib ^ -DCMAKE_PREFIX_PATHC:/Qt/5.15.2/msvc2019_64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/vlc-qt-install逐项说明-G指定生成器必须和你装的 VS 版本对应-A x64指定 64 位和 SDK 位数一致LIBVLC_INCLUDE_DIR是头文件根目录注意不要指到sdk/include/vlc要指到sdk/include因为源码里写的是#include vlc/vlc.hLIBVLC_LIBRARY和LIBVLC_CORE_LIBRARY分别对应两个导入库少一个都会在链接阶段报未解析的外部符号CMAKE_PREFIX_PATH告诉 CMake 去哪找 Qt 的Qt5CoreConfig.cmakeCMAKE_INSTALL_PREFIX是make install时的输出目录编出来的 DLL 和头文件会放到这里。提示路径统一用正斜杠/即使你在 Windows 上。CMake 能识别正斜杠但反斜杠在某些生成器里会被当转义符导致路径解析失败。3.3 生成与编译从 sln 到 DLLCMake 配置成功后build 目录下会生成vlc-qt.sln。用 Visual Studio 打开或者直接用命令行编译cmake --build . --config Release --target install这条命令做三件事按 Release 配置编译、编译所有目标、把产物安装到CMAKE_INSTALL_PREFIX。编译完成后去D:/dev/vlc-qt-install下看应该有bin/VlcQtCore.dll、bin/VlcQtWidgets.dll、lib/VlcQtCore.lib、lib/VlcQtWidgets.lib和include/下一堆头文件。如果你只要 Core 不要 Widgets可以在 CMake 里加-DBUILD_WIDGETSOFF但大多数做播放器的场景都需要 Widgets因为视频窗口的嵌入靠的就是VlcWidgetVideo这个类。编译过程中如果报cannot find -lpublic这通常是 qmake 路线的遗留错误在 CMake 下对应的是LIBVLC_LIBRARY没设对CMake 找不到libvlc.lib就会把库名当字符串传给链接器链接器再去找public.lib这种不存在的文件。检查你的LIBVLC_LIBRARY路径是否指向了实际存在的.lib文件。4. 避坑与排查编译 vlc-qt 最常见的五类报错4.1 现象CMake 报找不到 Qt5Core原因CMAKE_PREFIX_PATH没设或者设到了 Qt 的根目录而不是编译器专属目录。Qt 的 CMake 配置文件在C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5Core下CMAKE_PREFIX_PATH要指到msvc2019_64这一层。解决确认路径存在lib/cmake/Qt5Core/Qt5CoreConfig.cmake然后重新跑 CMake加-DCMAKE_PREFIX_PATHC:/Qt/5.15.2/msvc2019_64。如果还不行用-DQt5Core_DIRC:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5Core直接指定。4.2 现象链接阶段报unresolved external symbol libvlc_xxx原因LIBVLC_LIBRARY或LIBVLC_CORE_LIBRARY只设了一个或者设的.lib文件是 32 位的而工程是 64 位。VLC SDK 的lib目录下通常有libvlc.lib和libvlccore.lib两个vlc-qt 的 Core 模块两个都要链。解决在 CMake 命令里同时传两个变量并确认dumpbin /headers libvlc.lib | findstr machine输出的机器类型是 x64。如果是 x86换 64 位 SDK。4.3 现象编译通过但运行时报缺少libvlc.dll原因VlcQtCore.dll依赖libvlc.dll和libvlccore.dll这两个 DLL 在 VLC SDK 的根目录下不在sdk/lib里。编译时链接的是.lib运行时需要.dll。解决把 VLC SDK 根目录下的libvlc.dll、libvlccore.dll以及整个plugins目录拷到你自己的 exe 旁边。plugins目录不能少否则播放时会报找不到解码器。常见做法是写个批处理编译后自动拷贝。4.4 现象qmake 路线报cannot find -lpublic原因这是 vlc-qt 旧版.pro文件里的一个历史遗留LIBS -lpublic本意是链接某个库但 Windows 下没有public.lib。这个错误在 CMake 路线不会出现如果你在用 qmake说明你拉的分支太老。解决换 CMake 构建或者手动在.pro里把-lpublic删掉改成显式路径LIBS -LD:/dev/vlc-sdk/sdk/lib -lvlc -lvlccore。但更推荐直接切 CMake省得跟 qmake 的变量名较劲。4.5 现象编译出来的 DLL 在 Debug 模式下崩溃原因VLC SDK 是 Release 版编译的你的 Qt 工程如果用 Debug 配置去链 Release 的.libCRT 版本不一致堆内存跨模块释放时就会崩。这是 Windows 上 C 跨 DLL 的经典坑。解决vlc-qt 本身用 Release 编你的主工程也统一用 Release或者在 Debug 下用-DCMAKE_BUILD_TYPERelWithDebInfo。不要混用 Debug 和 Release 的 Qt 库。5. 把 vlc-qt 集成进自己的工程从 DLL 到可播放窗口5.1 工程里怎么引 vlc-qt编出 DLL 和头文件之后在你的 Qt 工程里集成有两种方式。一种是直接链安装目录下的.lib另一种是把 vlc-qt 源码作为子目录add_subdirectory进来。前者适合你已经编好一份固定版本后者适合你要改 vlc-qt 源码。链.lib的 CMake 写法find_package(Qt5 COMPONENTS Core Widgets REQUIRED) set(VLCQT_ROOT D:/dev/vlc-qt-install) target_include_directories(MyPlayer PRIVATE ${VLCQT_ROOT}/include ) target_link_libraries(MyPlayer PRIVATE ${VLCQT_ROOT}/lib/VlcQtCore.lib ${VLCQT_ROOT}/lib/VlcQtWidgets.lib Qt5::Core Qt5::Widgets )这段配置把 vlc-qt 的头文件目录加进编译搜索路径再把两个.lib链进来。注意VLCQT_ROOT指向你install的目录不是源码目录。头文件里#include VlcQtCore/MediaPlayer.h这种写法要求 include 路径指到include这一层。5.2 一个最小可播放窗口的代码下面这段代码创建一个窗口里面嵌一个VlcWidgetVideo然后播放一个本地文件。这是验证 vlc-qt 是否真正可用的最小闭环。#include QApplication #include VlcQtCore/Instance.h #include VlcQtCore/MediaPlayer.h #include VlcQtCore/Media.h #include VlcQtWidgets/WidgetVideo.h int main(int argc, char *argv[]) { QApplication app(argc, argv); // 创建 VLC 实例可传参数如 --no-video-title-show VlcInstance *instance new VlcInstance(VlcCommon::args(), app); // 创建播放器和视频窗口 VlcMediaPlayer *player new VlcMediaPlayer(instance); VlcWidgetVideo *videoWidget new VlcWidgetVideo(player); videoWidget-resize(800, 600); videoWidget-show(); // 加载媒体并播放 VlcMedia *media new VlcMedia(D:/test.mp4, true, instance); player-open(media); return app.exec(); }逻辑说明VlcInstance是整个 VLC 运行时的入口一个进程一个就够VlcMediaPlayer负责播放控制VlcWidgetVideo是 Qt 窗口部件内部通过setVideoWidget把播放器的视频输出绑定到窗口句柄上。VlcMedia的第二个参数true表示本地文件如果是网络流传false。参数VlcCommon::args()返回一组默认命令行参数你可以自己拼一个QStringList传进去比如加--network-caching300调网络缓冲。5.3 运行时的 DLL 部署清单编译出来的 exe 要能跑旁边必须有这些文件文件/目录来源作用VlcQtCore.dllvlc-qt 编译产物vlc-qt 核心封装VlcQtWidgets.dllvlc-qt 编译产物视频窗口部件libvlc.dllVLC SDK 根目录VLC 运行时libvlccore.dllVLC SDK 根目录VLC 核心运行时plugins/VLC SDK 根目录解码器、输出模块plugins目录必须整个拷不能只挑几个。VLC 在运行时会根据媒体类型动态加载对应的插件缺一个就可能导致某种格式播不了。常见做法是在 CMake 里加一个POST_BUILD自定义命令编译完自动xcopy这些文件到输出目录。6. 进阶用 windeployqt 打包与版本升级时的重编策略6.1 打包时别漏了 VLC 的 pluginsQt 工程发布时习惯用windeployqt自动拷 Qt 的 DLL但它不认识 vlc-qt 和 libvlc 的依赖。我一般会在windeployqt之后再手动补三样VlcQtCore.dll、VlcQtWidgets.dll、以及整个 VLC SDK 的运行时文件。libvlc.dll和libvlccore.dll直接放 exe 旁边plugins目录保持原结构放同级。一个容易忽略的点是 VLC 的plugins目录里还有一层plugins/plugins.dat缓存文件这个文件是 VLC 扫描插件后生成的如果你拷贝时漏了它首次启动会重新扫描慢几秒但不影响功能。但如果你的目标机器没有写权限扫描失败就会导致插件加载不了。稳妥做法是把plugins.dat一起拷过去。6.2 升级 VLC SDK 后必须全量重编vlc-qt 编译时会把 libvlc 的头文件路径和库路径写进 CMake 缓存如果你换了 VLC SDK 版本但没清缓存CMake 可能还在用旧的路径。更隐蔽的问题是libvlc 的 ABI 在小版本之间偶尔会变比如 VLC 3.0.16 到 3.0.18 之间某个结构体字段顺序调整过。这种情况下你用旧 SDK 编的 vlc-qt DLL 去链新 SDK 的libvlc.dll运行时可能直接崩在libvlc_new里。我的习惯是每次换 VLC SDK先删掉 build 目录重新跑一遍 CMake再全量编译。不要试图增量编译CMake 的依赖追踪在这种跨版本场景下不可靠。重编完之后用dumpbin /dependents VlcQtCore.dll确认它依赖的libvlc.dll版本号和你部署的一致。6.3 一个验证编译是否真正成功的检查清单编完不等于能用。我一般会走一遍这个检查第一dumpbin /exports VlcQtCore.dll看有没有导出VlcInstance相关的符号第二写个最小 Qt 工程链上去能编译过第三运行起来能播一个本地 mp4第四把 exe 拷到一台没装 Qt 和 VLC 的机器上补全 DLL 后还能播。这四步走完才算这份 vlc-qt 编译产物真正可用。从那以后我每次在 Windows 上编 vlc-qt都强制先确认 SDK 位数、Qt 编译器、CMake 路径三者一致再动手。希望帮到你。本文还有配套的精品资源点击获取