简介面向需要在 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.2LTS、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 方案 AMinGW Qt Creator最省心的一条路如果你只是想把 vlc-qt 编出来并且后面用 Qt Creator 开发播放器我强烈建议先走 MinGW 路线。原因很简单VLC 官方 Windows 开发包就是用 MinGW 编的你用同一套工具链去编 vlc-qtlibvlc.dll.a、libvlccore.dll.a直接链接CMake 识别路径也干脆。这套方案我不需要做任何额外的“格式转换”全程解压、配置、编译、安装一条龙下来基本没有物理障碍。具体组合建议Qt5.15.2 LTS安装时选择mingw81_64这一套编译器跟 Qt 安装包自带的 MinGW 8.1 保持一致不要自己另装别的 MinGWVLC 开发包3.0.20 win64 版本CMake3.20 以上带 GUI 也行命令行更直白注意Qt 在线安装器里那个 MinGW 版本和 VLC 官方 SDK 的 GNUC 版本不需要完全一致但位数必须一致否则后面链接libvlc.dll.a会直接报格式错误。2.2 方案 BMSVC 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 版本匹配核对表先把地基打牢我整理了一份自用的参考表编译前对着核一遍能排除掉六成以上的环境问题项MinGW 方案MSVC 方案Qt 版本5.15.2mingw81_645.15.2msvc2019_64编译器Qt 自带 MinGW 8.1VS2019 / VS2022 MSVC x64VLC SDKvlc-3.0.20-win64.7z 开发包同左但需要处理.dll.a导入库构建器mingw32-makecmake --build . --config Release播放器运行时VLCSDK 里bin/全部 DLL同左推荐度高中适合 VS 深度用户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 自带的 MinGWmingw32-make在 Qt 安装目录的Tools/mingw810_64/bin下面可能需要手动把它加进 PATH。CMake 建议直接用独立安装版不要用 Qt Creator 内置的那个因为命令行版本更便于排查路径问题。4. CMake 配置与构建实操从 clone 到出 lib4.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_PATHD:/dev/Qt/5.15.2/mingw81_64 \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIXD:/dev/vlc-qt-install \ -DVLCCORE_INCLUDE_DIRD:/dev/vlc-3.0.20-win64/include/vlc \ -DVLCCORE_LIBRARYD:/dev/vlc-3.0.20-win64/lib/libvlccore.dll.a \ -DVLCLIB_LIBRARYD:/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_PATHD:/dev/Qt/5.15.2/msvc2019_64 \ -DCMAKE_INSTALL_PREFIXD:/dev/vlc-qt-install-msvc \ -DVLCCORE_INCLUDE_DIRD:/dev/vlc-3.0.20-win64/include/vlc \ -DVLCCORE_LIBRARYD:/dev/vlc-3.0.20-win64/lib/libvlccore.dll.a \ -DVLCLIB_LIBRARYD:/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 Release4.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”。解决方式有两个把D:/dev/vlc-qt-install/bin下的vlc-qt.dll和D:/dev/vlc-3.0.20-win64/bin下的所有 DLL 拷到 exe 同目录。调试阶段更推荐在 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 常见错误速查表报错或现象大概率原因解决办法Could NOT find VLCVLCCORE_INCLUDE_DIR路径给错或只下载了播放器没下开发包用开发包把路径指到include/vlcCannot find -lvlc或.dll.a文件无法识别工具链和 VLC SDK 位数不匹配或 CMake 没找到库路径检查 x86/x64 一致显式指定VLCLIB_LIBRARY编译时一票unresolved external symbolQt 版本、/MD或/MT运行时配置不一致或 Debug 工程链了 Release 库统一工具链和构建类型清空 build 重新生成运行时找不到libvlc.dllPATH没有 SDK 的 bin 目录或 DLL 没拷到 exe 旁加 PATH 或手动拷 DLLQt6 下QWidget相关代码报错vlc-qt 对 Qt6 支持不完整换回 Qt 5.15 LTSCMake 已配置过但突然丢了路径CMakeCache.txt 污染删除 build 目录或 Cache 文件重新 configure6.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 假如你想从零开始避开所有弯路把整个流程压缩成一份“闭眼抄”清单大概是这样下载 Qt 5.15.2MinGW 64 位安装时勾选对应编译器。下载 VLC 3.0.20 win64 开发包解压把bin加入 PATH。拉取 vlc-qt 源码目录。使用cmake -G MinGW Makefiles配置注意把VLCCORE_INCLUDE_DIR指到include/vlc把两个库路径指到.dll.a文件。mingw32-make然后mingw32-make install。新工程里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 相关的适配更成熟了我再回来更新一篇新工具链的编译心得。本文还有配套的精品资源点击获取
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.2LTS、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 方案 AMinGW Qt Creator最省心的一条路如果你只是想把 vlc-qt 编出来并且后面用 Qt Creator 开发播放器我强烈建议先走 MinGW 路线。原因很简单VLC 官方 Windows 开发包就是用 MinGW 编的你用同一套工具链去编 vlc-qtlibvlc.dll.a、libvlccore.dll.a直接链接CMake 识别路径也干脆。这套方案我不需要做任何额外的“格式转换”全程解压、配置、编译、安装一条龙下来基本没有物理障碍。具体组合建议Qt5.15.2 LTS安装时选择mingw81_64这一套编译器跟 Qt 安装包自带的 MinGW 8.1 保持一致不要自己另装别的 MinGWVLC 开发包3.0.20 win64 版本CMake3.20 以上带 GUI 也行命令行更直白注意Qt 在线安装器里那个 MinGW 版本和 VLC 官方 SDK 的 GNUC 版本不需要完全一致但位数必须一致否则后面链接libvlc.dll.a会直接报格式错误。2.2 方案 BMSVC 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 版本匹配核对表先把地基打牢我整理了一份自用的参考表编译前对着核一遍能排除掉六成以上的环境问题项MinGW 方案MSVC 方案Qt 版本5.15.2mingw81_645.15.2msvc2019_64编译器Qt 自带 MinGW 8.1VS2019 / VS2022 MSVC x64VLC SDKvlc-3.0.20-win64.7z 开发包同左但需要处理.dll.a导入库构建器mingw32-makecmake --build . --config Release播放器运行时VLCSDK 里bin/全部 DLL同左推荐度高中适合 VS 深度用户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 自带的 MinGWmingw32-make在 Qt 安装目录的Tools/mingw810_64/bin下面可能需要手动把它加进 PATH。CMake 建议直接用独立安装版不要用 Qt Creator 内置的那个因为命令行版本更便于排查路径问题。4. CMake 配置与构建实操从 clone 到出 lib4.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_PATHD:/dev/Qt/5.15.2/mingw81_64 \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIXD:/dev/vlc-qt-install \ -DVLCCORE_INCLUDE_DIRD:/dev/vlc-3.0.20-win64/include/vlc \ -DVLCCORE_LIBRARYD:/dev/vlc-3.0.20-win64/lib/libvlccore.dll.a \ -DVLCLIB_LIBRARYD:/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_PATHD:/dev/Qt/5.15.2/msvc2019_64 \ -DCMAKE_INSTALL_PREFIXD:/dev/vlc-qt-install-msvc \ -DVLCCORE_INCLUDE_DIRD:/dev/vlc-3.0.20-win64/include/vlc \ -DVLCCORE_LIBRARYD:/dev/vlc-3.0.20-win64/lib/libvlccore.dll.a \ -DVLCLIB_LIBRARYD:/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 Release4.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”。解决方式有两个把D:/dev/vlc-qt-install/bin下的vlc-qt.dll和D:/dev/vlc-3.0.20-win64/bin下的所有 DLL 拷到 exe 同目录。调试阶段更推荐在 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 常见错误速查表报错或现象大概率原因解决办法Could NOT find VLCVLCCORE_INCLUDE_DIR路径给错或只下载了播放器没下开发包用开发包把路径指到include/vlcCannot find -lvlc或.dll.a文件无法识别工具链和 VLC SDK 位数不匹配或 CMake 没找到库路径检查 x86/x64 一致显式指定VLCLIB_LIBRARY编译时一票unresolved external symbolQt 版本、/MD或/MT运行时配置不一致或 Debug 工程链了 Release 库统一工具链和构建类型清空 build 重新生成运行时找不到libvlc.dllPATH没有 SDK 的 bin 目录或 DLL 没拷到 exe 旁加 PATH 或手动拷 DLLQt6 下QWidget相关代码报错vlc-qt 对 Qt6 支持不完整换回 Qt 5.15 LTSCMake 已配置过但突然丢了路径CMakeCache.txt 污染删除 build 目录或 Cache 文件重新 configure6.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 假如你想从零开始避开所有弯路把整个流程压缩成一份“闭眼抄”清单大概是这样下载 Qt 5.15.2MinGW 64 位安装时勾选对应编译器。下载 VLC 3.0.20 win64 开发包解压把bin加入 PATH。拉取 vlc-qt 源码目录。使用cmake -G MinGW Makefiles配置注意把VLCCORE_INCLUDE_DIR指到include/vlc把两个库路径指到.dll.a文件。mingw32-make然后mingw32-make install。新工程里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 相关的适配更成熟了我再回来更新一篇新工具链的编译心得。本文还有配套的精品资源点击获取
