简介面向需要在 Windows 上把 VLC 播放能力集成到 Qt 工程的 C/Qt 开发者这份资料围绕 vlc-qt 1.1.1 的编译产物整理适合音视频播放器开发、二次封装、环境搭建与编译验证。压缩包共 77 个文件约 36.71MB以 38 个 h 头文件、17 个 cmake 配置、10 个 dll 动态库和 8 个 lib 导入库为主并附 vlc-3.0.0-win64.7z 与 vlc-qt-1.1.1.tar.gz覆盖源码、运行时依赖和 debug/release 两套预编译库头文件用于接口声明CMake 文件便于工程查找依赖dll/lib 可直接参与链接。目录按 VLCQtCore、VLCQtWidgets、VLCQtQml 等模块组织并含 qmldir、qmltypes 等 QML 元数据。已有 1920 人学习下载。读者可据此复用编译后的库与依赖搭配减少依赖获取与链接配置成本也便于对照自身工程核对 debug 与 release 配置。1. Windows 下编译 VLC-Qt真正花时间的是让 DLL 出现在正确的位置而不是输入那几行 CMake桌面端要在 Qt 界面里嵌一路播放器不想拖浏览器内核最常见的落点就是把 libVLC 包一层VLC-Qt 正是这层壳。它在 Linux 上一路cmake make就过去了到了 Windows同样几条命令会先卡在“找不到 libvlc.lib”再卡在“插件加载失败”最后卡在“编过了但一直黑屏”。这篇只讲在 Windows 下把 VLC-Qt 从源码编出来、装进 Qt 工程、跑到能出画面的完整路径包括位数对齐、Debug/Release 取舍、DLL 与 plugins 目录怎么放这些才是真正消耗时间的环节。适合已经能用 CMake 和 Qt Creator 建工程、准备自建播放模块的桌面端开发者。2. 编译前先对齐三件套Qt 套件、libVLC SDK、CMake 生成器2.1 VLC-Qt 只是薄壳真正决定成败的是 libVLC 的二进制形态VLC-Qt 这个名字容易让人误以为它是一个完整播放器实际它只做一件事把 libVLC 的 C 接口包成 QObject 风格的类VlcInstance、VlcMediaPlayer、VlcWidgetVideo底下全是libvlc_*调用。编译 VLC-Qt 的整个过程中libVLC 本体一行都不会被编译你面对的是一个预编译好的二进制 SDK。这件事直接决定了 Windows 上的动手顺序先把 libVLC SDK 的形态确认清楚再谈 VLC-Qt 怎么编。一个可用的 SDK 必须同时给出三样东西——头文件以vlc/vlc.h为入口的那一套、导入库MSVC 下是.lib、以及运行时libvlc.dll、libvlccore.dll加上整个plugins目录。这三样少任何一样后面都会以完全不同的报错形式还给你。关键认知在于导入库不是代码它只是一张符号索引表。链接期 CMake 拿着这张表去核对符号名运行期 Windows 加载器再去磁盘上找.dll。所以“链接通过”和“跑得起来”是两个独立关卡报错长得完全不一样这也是新手最容易把两类问题混在一起排查的地方。还有一层容易被忽略plugins目录才是 libVLC 真正的解码能力所在。dll 本身只有调度逻辑解封装、解码、输出全靠插件。很多“能编译、能链接、能启动就是不出画面”的案子根子在插件目录没摆对而不是代码写错了。2.2 用 dumpbin 与 qmake -query 把位数和运行库固定下来Windows 上最没技术含量、又最容易出错的一类问题是位数不匹配。x64 的 exe 链 x86 的 lib 会直接报 LNK1112x64 进程加载 x86 的 dll 会在启动瞬间退出去日志里只留一行看不懂的东西。开工前花两分钟确认能省掉后面半小时的猜谜。:: 在 “x64 Native Tools 命令提示符” 里执行不要用普通 cmd :: 1) 看 libVLC 导入库的目标架构 dumpbin /headers VLC_SDK_DIR\sdk\lib\libvlc.lib | findstr /i machine :: 2) 看打算使用的 Qt 套件是什么架构 dumpbin /headers QT_DIR\bin\Qt5Core.dll | findstr /i machine :: 3) 看 libVLC 运行时依赖哪些 CRT判断要不要装运行库 dumpbin /dependents VLC_SDK_DIR\libvlc.dlldumpbin /headers的输出里machine (x64)或machine (x86)就是答案两处必须一致。第三条命令的输出同样值得看一眼如果libvlc.dll依赖MSVCP140.dll、VCRUNTIME140.dll这类名字说明目标机器上要有对应的运行库否则用户那边会以“缺 dll”的形式失败——而你的开发机上往往早就装过了根本复现不了。qmake -query QT_INSTALL_PREFIX能告诉你当前 Qt 套件的安装前缀把它记下来后面CMAKE_PREFIX_PATH要用。Qt 5 和 Qt 6 在这一步就要做出选择VLC-Qt 的主线代码长期围绕 Qt 5 演进直接用 Qt 6 编大概率会在QDesktopWidget、QRegExp这类早已移除的 API 上翻车Qt 6 需要你自己打补丁适配别在这上面浪费时间。提示dumpbin只在 Visual Studio 的开发者命令提示符里可用。如果你用 MinGW 工具链用objdump -f看架构用objdump -p看依赖。2.3 先把目录摆成 CMake 认得的形状拿到 SDK 压缩包后别急着解压完就直接编。libVLC 的分发包里include、lib和运行时的libvlc.dll、plugins通常不在同一层目录混在一起会让后面的路径变量写得很难看。我一般会先手工整理成一个固定形状写进一个文本文件备查目录应该放什么谁在用VLC_SDK_DIR\sdk\include\vlc\vlc.hlibVLC 头文件入口编译期 includeVLC_SDK_DIR\sdk\lib\libvlc.libMSVC 导入库链接期VLC_SDK_DIR\sdk\lib\libvlccore.lib核心导入库部分符号在这里链接期VLC_SDK_DIR\libvlc.dll运行时部署VLC_SDK_DIR\plugins\全部解码/输出插件运行时对应地CMake 侧要喂的变量也就那么几个CMake 变量指向说明CMAKE_PREFIX_PATHQt 前缀 VLC-Qt 安装前缀多个路径用分号分隔别用逗号LIBVLC_INCLUDE_DIR...\sdk\include目录下应当直接存在vlc\vlc.hLIBVLC_LIBRARY...\sdk\lib\libvlc.lib位数必须与目标一致LIBVLC_LIBRARY_CORE...\sdk\lib\libvlccore.lib有些版本不强制缺了会报未解析符号不同发行版本的变量名可能是复数形式LIBVLC_INCLUDE_DIRS、LIBVLC_LIBRARIES。与其背不如配一次就打开cmake-gui看缓存区里实际出现了哪些名字照着填最稳。这一步做完后面的 configure 才有意义。3. 从源码到 .lib 和 .dllVLC-Qt 的配置、构建与安装三段式3.1 生成阶段把 CMAKE_PREFIX_PATH 一次喂对VLC-Qt 的构建分三段configure 生成工程文件、build 出二进制、install 整理成一个可被find_package消费的前缀。第一段最容易反复因为 CMake 会缓存上一次的错误结果改完变量不删缓存就会一直报同样的错。:: 建议每次重来都先删掉 build 目录别在脏缓存上反复试 cmake -S VLCQT_SRC -B VLCQT_BUILD ^ -G Visual Studio 17 2022 -A x64 ^ -DCMAKE_PREFIX_PATHQT_DIR;VLCQT_INSTALL ^ -DLIBVLC_INCLUDE_DIRVLC_SDK_DIR/sdk/include ^ -DLIBVLC_LIBRARYVLC_SDK_DIR/sdk/lib/libvlc.lib ^ -DLIBVLC_LIBRARY_COREVLC_SDK_DIR/sdk/lib/libvlccore.lib ^ -DCMAKE_INSTALL_PREFIXVLCQT_INSTALL ^ -DBUILD_EXAMPLESOFF ^ -DBUILD_TESTSOFF逐项说清楚-G的生成器字符串必须和你本机装的 VS 版本对应敲cmake --help能看到全部可选值写错了会直接提示找不到生成器-A x64是平台参数只对 VS 系列生成器有效用 Ninja 或 MinGW Makefiles 时不要带。CMAKE_PREFIX_PATH里放 Qt 前缀是为了让 CMake 找到Qt5Config.cmake放 VLC-Qt 前缀是为了让下游工程能找到VLCQtCoreConfig.cmake两者用分号连接用分号而不是逗号这一点经常被写错。BUILD_EXAMPLES和BUILD_TESTS关掉能明显缩短构建时间也避免示例工程自身的额外依赖把 configure 拖挂。选项名在不同分支上可能是BUILD_TESTS也可能是别的写法configure 完成后看输出里的 “Configuring done” 之前那段选项列表比照着自己需要的改。注意多配置生成器VS、Xcode会忽略CMAKE_BUILD_TYPE。在 VS 生成器下写-DCMAKE_BUILD_TYPERelease不会有任何效果配置由--config在构建期决定。3.2 构建阶段Debug 与 Release、静态与动态的真实取舍:: 先只编 Release跑通了再补 Debug别一上来两个都编 cmake --build VLCQT_BUILD --config Release --target install --parallel :: 需要调试期符号时再补一次 cmake --build VLCQT_BUILD --config Debug --target install --parallel--target install一步到位省掉单独再敲cmake --install。--parallel不带数字时按 CPU 核数走机器内存小的话显式写--parallel 8之类避免链接阶段 OOM。关于 Debug/Release血泪经验是libVLC 那个 dll 是 Release 构建的它的堆和 CRT 状态跟你的 Debug 版进程并不共享。只要你不跨 DLL 边界传递new出来的对象、不走 C 异常穿越边界用 Debug 配置链接 Release 的导入库通常没事但一旦你在 Debug 下把VlcMedia这类包装对象在自己模块里 new 了又交给库去 delete堆断言就会在播放几秒后冒出来。稳妥做法是日常联调用 Release要断点排查自己那层逻辑时再切 Debug。静态链接是另一个常见误区。libVLC 在 Windows 下基本不提供可用的静态库它的插件机制本身就依赖动态加载WITH_STATIC_LIBVLC这个选项在 Windows 上大概率走不通。VLC-Qt 自身可以编成静态库但那只是把壳静态化底下的 libVLC 依然是 dll收益有限反而让部署时多一层困惑。默认走动态就好。3.3 安装阶段install 之后前缀下应该看到什么构建成功不等于能被消费。install之后到你指定的前缀下逐项核对缺一项下游工程就会以一个看起来毫不相关的错误失败路径内容缺失后的典型症状include/VLCQtCore/Core 模块头文件编译期VLCQtCore/Media.h: No such fileinclude/VLCQtWidgets/Widgets 模块头文件只有 Core 编得过Widgets 编不过lib/VLCQtCore.lib导入库链接期 LNK2019 一堆未解析符号bin/VLCQtCore.dll运行时启动即报缺 dlllib/cmake/VLCQtCore/CMake 包配置find_package直接失败如果lib/cmake下面空空如也说明这次构建没有生成包配置文件下游只能退回到手工include_directories加target_link_libraries的土办法。能修就修土办法一旦工程多了会非常难维护。4. 把 VLC-Qt 接进 Qt 工程一个能出画面的最小播放器4.1 CMakeLists 里 find_package 与 target_link_libraries 怎么写cmake_minimum_required(VERSION 3.16) project(MyPlayer LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) # VLC-Qt 的类带 Q_OBJECT必须开 find_package(Qt5 COMPONENTS Core Gui Widgets REQUIRED) find_package(VLCQtCore CONFIG REQUIRED) find_package(VLCQtWidgets CONFIG REQUIRED) add_executable(MyPlayer main.cpp playerwindow.cpp playerwindow.h) target_link_libraries(MyPlayer PRIVATE Qt5::Widgets VLCQtCore VLCQtWidgets)CONFIG是必须的它告诉 CMake 走VLCQtCoreConfig.cmake这条路而不是去FindXXX.cmake的模块目录里瞎找。CMAKE_AUTOMOC一定要开VLC-Qt 的类全部带Q_OBJECT漏了会在链接期出现vtable for ...未解析这种极其迷惑的错误。如果find_package报找不到先别怀疑人生去VLCQT_INSTALL/lib/cmake/下面看目录名到底叫什么。有些构建出来的包名和你想的不一样target 名也可能不是VLCQtCore。打开VLCQtCoreTargets.cmake里面add_library(...)后面的那个名字才是能直接链接的 target 名。4.2 初始化、挂窗口、播放三段代码与它们的时序// playerwindow.cpp —— 只保留能出画面的最小路径 #include playerwindow.h #include VLCQtCore/Common.h #include VLCQtCore/Instance.h #include VLCQtCore/Media.h #include VLCQtCore/MediaPlayer.h #include VLCQtWidgets/WidgetVideo.h #include QVBoxLayout PlayerWindow::PlayerWindow(QWidget *parent) : QWidget(parent) { // 1) 实例带 --verbose2 让 libVLC 把自己的日志吐出来 QStringList args VlcCommon::args(); args --verbose2; m_instance new VlcInstance(args, this); // 2) 播放器所有播放状态挂在它身上生命周期要比视频窗口长 m_player new VlcMediaPlayer(m_instance, this); // 3) 视频窗口先建窗口再 setVideoWidget顺序反了就是永久黑屏 m_video new VlcWidgetVideo(m_player, this); m_player-setVideoWidget(m_video); auto *layout new QVBoxLayout(this); layout-setContentsMargins(0, 0, 0, 0); layout-addWidget(m_video); } void PlayerWindow::playUrl(const QString url) { // localFilefalse 表示按 URL/流地址处理读本地文件时传 true auto *media new VlcMedia(url, false, m_instance); m_player-open(media); // open 是异步的返回不代表已经出画面 }三个对象的依赖顺序不能乱VlcInstance是全局上下文VlcMediaPlayer依赖它VlcWidgetVideo又依赖 player。setVideoWidget必须在窗口句柄已经创建之后调用如果你把它写在构造函数的极早期、窗口还没show()libVLC 拿到的窗口句柄是无效的画面就永远出不来。稳妥做法是让VlcWidgetVideo先于setVideoWidget完成构造再在showEvent之后确认一次。VlcCommon::args()返回一组经过筛选的启动参数比手工拼靠谱。加上--verbose2是排查期最有用的一招libVLC 会把插件加载、解码器选择、输出模块初始化全部打到 stderr这是唯一的黑匣子。VlcMedia的第二个参数是“是不是本地文件”传错不会立刻报错而是表现为一直缓冲、永远不播。传完open之后立刻返回是正常的状态变化要走信号别写成同步等待。4.3 打包windeployqt 之后还必须手工补的两样东西:: 1) 先把 Qt 依赖铺开 windeployqt --release OUT_DIR\MyPlayer.exe :: 2) 补 libVLC 的两个运行时 dll copy VLC_SDK_DIR\libvlc.dll OUT_DIR\ copy VLC_SDK_DIR\libvlccore.dll OUT_DIR\ :: 3) 整目录拷插件少一个就少一类格式 xcopy /E /I /Y VLC_SDK_DIR\plugins OUT_DIR\pluginswindeployqt只认 Qt 自己的依赖图它完全不知道 libVLC 的存在上面第 2、3 步必须手工补。plugins目录必须和libvlc.dll保持相对位置关系libVLC 会依据 dll 所在路径去推算插件目录如果你把它挪到别处就得通过环境变量或启动参数显式指过去否则启动时会看到“插件加载失败”但程序不崩只是什么都不能播。5. 编译与运行阶段的避坑清单五种典型翻车现场5.1 LNK2019 找不到__imp_libvlc_*符号现象编译全过链接阶段报一串unresolved external symbol __imp_libvlc_media_new_location之类的错误数量从几个到几十个不等。原因__imp_前缀意味着链接器在找导入库说明.lib根本没被链上或者只链了libvlccore.lib而漏了libvlc.lib。也可能是LIBVLC_LIBRARY指到了一个不存在的路径CMake 默默忽略没报错。解决先确认LIBVLC_LIBRARY指向的文件真实存在再用dumpbin /headers核对位数。如果两样都对还是报就去 CMakeCache.txt 里搜LIBVLC看最终生效的是哪个值——缓存里的旧值经常在作祟删掉 build 目录重来一次往往就好了。5.2 启动就报缺 dll或者进程一闪而过现象开发机上跑得好好的拷到干净机器上双击没反应或者弹窗提示找不到libvlc.dll。原因运行时 dll 没跟 exe 放在同一目录。Windows 加载器按 exe 目录、系统目录、PATH 的顺序找开发机上往往因为 PATH 里正好有 VLC 安装目录而侥幸通过一到干净机器立刻暴露。解决把libvlc.dll和libvlccore.dll直接放到 exe 同级目录plugins放成同级子目录。别依赖 PATH也别指望安装程序帮你配环境变量这两条在用户机器上都不可控。5.3 窗口出来了但一直黑屏日志里也没有明显报错现象播放器控件是黑的进度条不走或走了没画面控制台没异常。原因有三类setVideoWidget调用时机早于窗口句柄创建VlcMedia的localFile参数传错导致一直在缓冲plugins目录里缺视频输出模块比如 Windows 下需要的几种 vout 插件。解决先加--verbose2看日志重点找using video output module这句没有就是输出模块没加载有的话再检查setVideoWidget的调用位置把它挪到窗口show()之后的初始化里最后确认plugins目录是整目录拷贝而不是只挑了其中几个 dll。5.4 Debug 配置下播放几秒就崩在堆上现象Release 完全正常Debug 播放几秒后弹断言停在_CrtIsValidHeapPointer之类的地方。原因Debug 版 CRT 和 libVLC 那个 Release dll 使用的是两套堆。只要发生跨边界的内存释放就会命中堆校验。解决把联调配置切回 Release只在自己那层逻辑需要断点时临时切 Debug并且保证 Debug 下不把包装对象的所有权交给库。真要长期在 Debug 下开发就得接受“播放核心部分只能看日志不能断点”这个现实。5.5 find_package 报找不到 VLCQtCore 的配置文件现象下游工程 configure 阶段直接失败提示Could not find a package configuration file provided by VLCQtCore。原因要么 install 没执行成功lib/cmake下是空的要么CMAKE_PREFIX_PATH只写了 Qt 没写 VLC-Qt 的安装前缀要么写的是 build 目录而不是 install 前缀。解决去VLCQT_INSTALL/lib/cmake/下ls一遍确认有VLCQtCoreConfig.cmake。有的话检查CMAKE_PREFIX_PATH是不是被下游工程覆盖了用-DCMAKE_PREFIX_PATH...;...在命令行显式传一次比改 CMakeLists 更可靠。6. 把流程固化成脚本换一台机器也能复现的检查清单这套流程手动跑一遍要改十几处路径第二次换机器还得重来。我的习惯是把所有可变项提到脚本最上面下面全是固定动作谁接手都只改前五行:: build-vlcqt.cmd —— 换机器只改这一段 set VLCQT_SRCD:\src\vlc-qt set VLCQT_BUILDD:\build\vlc-qt set VLCQT_INSTALLD:\sdk\vlc-qt set QT_DIRC:\Qt\5.15\msvc2019_64 set VLC_SDKD:\sdk\vlc :: 下面不动 if exist %VLCQT_BUILD% rmdir /S /Q %VLCQT_BUILD% cmake -S %VLCQT_SRC% -B %VLCQT_BUILD% -G Visual Studio 17 2022 -A x64 ^ -DCMAKE_PREFIX_PATH%QT_DIR%;%VLCQT_INSTALL% ^ -DLIBVLC_INCLUDE_DIR%VLC_SDK%\sdk\include ^ -DLIBVLC_LIBRARY%VLC_SDK%\sdk\lib\libvlc.lib ^ -DCMAKE_INSTALL_PREFIX%VLCQT_INSTALL% || exit /b 1 cmake --build %VLCQT_BUILD% --config Release --target install --parallel || exit /b 1配套的验证清单我会做成一张表新机器上逐行打勾比事后回溯快得多检查点动作通过标准位数一致dumpbin /headers查 lib 与 Qt两者同为 x64 或同为 x86导入库可链编一个空工程链libvlc.lib无 LNK2019包配置存在看lib/cmake/目录有VLCQtCoreConfig.cmake运行时完整拷 dll 与 plugins 后启动日志里出现视频输出模块加载记录干净机可跑在没装过相关运行库的机器上试不弹缺 dll 提示最后说一个我踩过很多次的坑不要相信“开发机上能跑”。我最早一版在装了完整运行库的机器上验证通过就交付了结果到目标机器上连窗口都出不来排查半天才发现是 CRT 依赖。从那以后我的习惯是每次出包都留一台什么都没装过的虚拟机做最终验证插件目录是不是整目录拷的、dll 有没有漏一趟就能看明白。希望帮到你。本文还有配套的精品资源点击获取