简介这份资源是面向Windows 64位平台、希望在Qt环境中集成VLC播放能力的开发者所准备的编译安装包基于Qt5.15.2与VLC3.0.14采用mingw8.1.0_64工具链构建适合对Qt与VLC结合感兴趣、需要快速获得可用库文件的爱好者与工程人员。压缩包共399个文件约43.28MB其中338个dll提供运行时依赖38个h为开发头文件14个cmake与3个pc文件用于工程配置和依赖查找另有少量a静态库及qmltypes、qmldir等QML元数据整体覆盖了从编译产物到集成配置的完整链路。目前已有435人学习下载。借助其中的库文件与CMake配置读者可省去自行编译VLC-Qt的繁琐过程直接在自己的Qt项目中链接VLC核心、Widgets与Qml模块快速搭建带图形界面的媒体播放功能并参考其目录组织理解各模块的依赖关系与集成方式。1. 拿到 vlc-qt_build_mingw64_install.zip 先别急着解压它到底补上了哪块拼图如果你在 Windows 上用 Qt5.15.2 写过播放器大概率经历过这个场景UI 用 QWidget 搭好了进度条、音量条、播放列表都画完了结果卡在“怎么把 VLC 嵌进来”这一步。直接调 libvlc 的 C 接口不是不行但事件回调、窗口句柄绑定、QML 侧渲染这几件事混在一起代码很快就变成一团乱麻。vlc-qt_build_mingw64_install.zip 就是冲这个痛点来的——它是一份用 MinGW64 工具链预编译好的 VLC-Qt 集成库安装包对应 Qt5.15.2 VLC3.0.14 mingw8.1.0_64 这套组合。压缩包里没有源码全是编译产物libVLCQtCore.dll.a、libVLCQtWidgets.dll.a、libVLCQtQml.dll.a、libVLCQt.dll.a 四个导入库外加 VLCQtWidgetsTargets.cmake、VLCQtCoreTargets.cmake、VLCQtQmlTargets.cmake 等一组 CMake 配置文件。说白了它把“VLC-Qt 源码编译”这一步替你省了你拿到的是可以直接在 CMake 工程里 find_package 的成品。适合谁适合那些不想在 Windows 上折腾 MSVC 与 MinGW 混编、不想自己拉 VLC-Qt 源码配 CMake 的人。但注意它是 MinGW64 专用MSVC 工程用不了这是第一个硬边界。2. 拆包看结构四个 .dll.a 和一组 CMake 配置到底怎么配合2.1 导入库与运行时的分工先把这个包里的文件按角色分清楚不然后面 CMake 配错了都不知道错在哪。文件角色链接阶段运行阶段libVLCQtCore.dll.aCore 模块导入库需要需要对应 VLCQtCore.dlllibVLCQtWidgets.dll.aWidgets 模块导入库需要需要对应 VLCQtWidgets.dlllibVLCQtQml.dll.aQml 模块导入库需要需要对应 VLCQtQml.dlllibVLCQt.dll.a聚合模块导入库可选视链接方式VLCQt*Targets.cmake目标定义CMake 读取不参与VLCQt*ConfigVersion.cmake版本校验CMake 读取不参与关键点.dll.a是 MinGW 的导入库不是静态库。它只负责告诉链接器“这些符号在对应的 DLL 里”真正跑起来还需要 VLCQtCore.dll、VLCQtWidgets.dll 这些动态库在 PATH 或 exe 同目录下。很多人解压后只把.dll.a丢进工程编译过了一运行就报“找不到 VLCQtCore.dll”这就是没分清导入库和运行时的区别。2.2 CMake 配置文件的查找逻辑VLCQtCoreTargets.cmake 这类文件的作用是定义 imported target。当你在 CMakeLists.txt 里写find_package(VLCQtCore)时CMake 会去找 VLCQtCoreConfig.cmake再由它 include 对应的 Targets.cmake。这个包里给的是 Targets 和 ConfigVersion说明它期望你把它放到一个能被 CMAKE_PREFIX_PATH 找到的目录结构里。常见做法是保持 install 目录的原始层级比如vlc-qt-install/ lib/ cmake/ VLCQtCore/ VLCQtCoreTargets.cmake VLCQtCoreConfigVersion.cmake VLCQtWidgets/ ... libVLCQtCore.dll.a libVLCQtWidgets.dll.a然后在 CMakeLists.txt 里# 把 install 根目录加进前缀路径CMake 才能找到 lib/cmake 下的配置 list(APPEND CMAKE_PREFIX_PATH D:/sdk/vlc-qt-install) find_package(VLCQtCore REQUIRED) find_package(VLCQtWidgets REQUIRED) target_link_libraries(MyPlayer PRIVATE VLCQt::Core VLCQt::Widgets )这里VLCQt::Core和VLCQt::Widgets是 Targets.cmake 里定义的 imported target 名字。如果你 find_package 成功但 target_link_libraries 报“找不到目标”八成是 target 名字写错了去 Targets.cmake 里搜add_library看实际命名。提示不要手动去 linklibVLCQtCore.dll.a的绝对路径那样会绕过 CMake 的依赖传递include 路径和编译定义都得自己补容易漏。3. 从零搭一个最小可播放工程CMake 配置与 libvlc 运行时对齐3.1 工程目录与 CMakeLists.txt假设你已经把压缩包解压到D:/sdk/vlc-qt-installVLC3.0.14 的 SDK 在D:/sdk/vlc-3.0.14。新建一个 Qt Widgets 工程目录如下MyVlcPlayer/ CMakeLists.txt main.cpp playerwidget.h playerwidget.cppCMakeLists.txt 完整写法cmake_minimum_required(VERSION 3.16) project(MyVlcPlayer LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) # Qt5 路径按你本机 Qt5.15.2 mingw 安装位置改 list(APPEND CMAKE_PREFIX_PATH D:/Qt/5.15.2/mingw81_64) # VLC-Qt 预编译包路径 list(APPEND CMAKE_PREFIX_PATH D:/sdk/vlc-qt-install) # VLC SDK 路径libvlc 头文件和导入库在这里 list(APPEND CMAKE_PREFIX_PATH D:/sdk/vlc-3.0.14) find_package(Qt5 REQUIRED COMPONENTS Core Widgets) find_package(VLCQtCore REQUIRED) find_package(VLCQtWidgets REQUIRED) add_executable(MyVlcPlayer main.cpp playerwidget.cpp playerwidget.h ) target_link_libraries(MyVlcPlayer PRIVATE Qt5::Core Qt5::Widgets VLCQt::Core VLCQt::Widgets )逻辑说明CMAKE_PREFIX_PATH是一个列表CMake 会依次在这些前缀下找lib/cmake/PackageName/目录。VLC-Qt 的 Targets.cmake 里通常会通过find_dependency去拉 libvlc 的依赖所以 VLC SDK 路径也要加进去否则配置阶段会报“找不到 LibVLC”。参数说明CMAKE_AUTOMOC ON必须开因为 VLC-Qt 的类继承自 QObject有 Q_OBJECT 宏。CMAKE_CXX_STANDARD 17是 Qt5.15.2 的推荐值低于 14 可能编译不过。3.2 最小播放器代码playerwidget.h#pragma once #include QWidget #include VLCQtCore/MediaPlayer.h #include VLCQtCore/Instance.h #include VLCQtWidgets/WidgetVideo.h class PlayerWidget : public QWidget { Q_OBJECT public: explicit PlayerWidget(QWidget *parent nullptr); void playFile(const QString path); private: VlcInstance *m_instance nullptr; VlcMediaPlayer *m_player nullptr; VlcWidgetVideo *m_videoWidget nullptr; };playerwidget.cpp#include playerwidget.h #include QVBoxLayout #include VLCQtCore/Media.h PlayerWidget::PlayerWidget(QWidget *parent) : QWidget(parent) { // Instance 是 libvlc 的入口一个进程一个就够 m_instance new VlcInstance(VlcCommon::args(), this); m_player new VlcMediaPlayer(m_instance); m_videoWidget new VlcWidgetVideo(m_player, this); auto *layout new QVBoxLayout(this); layout-addWidget(m_videoWidget); setLayout(layout); } void PlayerWidget::playFile(const QString path) { // Media 负责加载具体文件play 之后视频渲染到 VlcWidgetVideo auto *media new VlcMedia(path, true, m_instance); m_player-open(media); }逻辑说明VlcInstance构造时传入VlcCommon::args()这是 VLC-Qt 提供的默认参数集避免手动拼--no-video-title-show之类的选项。VlcWidgetVideo内部会处理窗口句柄绑定你不需要自己调libvlc_media_player_set_hwnd。VlcMedia的第二个参数true表示本地文件网络流传false。参数说明VlcCommon::args()返回的是QStringList如果你需要加自定义参数比如--network-caching1000可以自己构造列表传进去。但注意VLC3.0.14 对某些参数有版本差异别照搬 VLC2.x 的写法。3.3 运行时 DLL 的摆放编译通过只是第一步。运行 exe 时需要以下 DLL 在可搜索路径下Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dllQt 安装目录的 bin 下VLCQtCore.dll、VLCQtWidgets.dllVLC-Qt 预编译包的 bin 或 lib 下libvlc.dll、libvlccore.dllVLC3.0.14 安装目录下plugins 目录VLC 的插件目录必须整体拷贝我一般会在 CMake 里加一个 post-build 拷贝add_custom_command(TARGET MyVlcPlayer POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different D:/sdk/vlc-qt-install/bin/VLCQtCore.dll $TARGET_FILE_DIR:MyVlcPlayer COMMAND ${CMAKE_COMMAND} -E copy_if_different D:/sdk/vlc-qt-install/bin/VLCQtWidgets.dll $TARGET_FILE_DIR:MyVlcPlayer COMMAND ${CMAKE_COMMAND} -E copy_directory D:/sdk/vlc-3.0.14/plugins $TARGET_FILE_DIR:MyVlcPlayer/plugins )注意plugins 目录必须和 exe 同级或者通过 VLC_PLUGIN_PATH 环境变量指定。少了 plugins播放器能启动但一播放就崩这是血泪经验。4. 避坑排查MinGW64 链接 VLC-Qt 最常见的五类翻车4.1 现象CMake 配置报 “Could not find a package configuration file provided by VLCQtCore”原因CMAKE_PREFIX_PATH 没指到 install 根目录或者目录层级不对。CMake 找的是prefix/lib/cmake/VLCQtCore/VLCQtCoreConfig.cmake如果你把 Targets.cmake 直接放在 install 根目录它找不到。解决保持压缩包解压后的原始层级把 install 根目录加进 CMAKE_PREFIX_PATH。如果压缩包里没有 Config.cmake 只有 Targets.cmake可以自己写一个最小的 Config.cmake# VLCQtCoreConfig.cmake include(${CMAKE_CURRENT_LIST_DIR}/VLCQtCoreTargets.cmake)4.2 现象链接阶段报 “undefined reference to _imp__libvlc_new”原因VLC-Qt 的导入库依赖 libvlc 的导入库但 CMake 没有把 VLC SDK 的 lib 目录传给链接器。Targets.cmake 里可能用了find_dependency(LibVLC)但你的 VLC SDK 路径没在 CMAKE_PREFIX_PATH 里。解决确认 VLC3.0.14 SDK 的sdk/lib下有 libvlc.dll.a 和 libvlccore.dll.a然后把 SDK 根目录加进 CMAKE_PREFIX_PATH。如果还是不行手动在 target_link_libraries 里补上绝对路径target_link_libraries(MyVlcPlayer PRIVATE D:/sdk/vlc-3.0.14/sdk/lib/libvlc.dll.a D:/sdk/vlc-3.0.14/sdk/lib/libvlccore.dll.a )4.3 现象编译通过运行时报 “找不到 VLCQtCore.dll”原因只链接了导入库没有把对应的 DLL 放到 exe 目录或 PATH 里。解决用 post-build 拷贝或者把 VLC-Qt 的 bin 目录加进系统 PATH。但改 PATH 是全局的容易和其他版本冲突我一般优先用拷贝。4.4 现象播放器窗口一片黑音频正常原因VlcWidgetVideo 没有正确绑定窗口句柄或者 VLC 的 video output 模块没加载。MinGW64 构建的 VLC-Qt 对VlcWidgetVideo的 winId 传递有时序要求如果在 show() 之前就 open media句柄可能无效。解决确保VlcWidgetVideo已经显示后再调playFile。可以在showEvent里延迟播放或者用QTimer::singleShot(0, ...)把 open 推到事件循环下一轮。4.5 现象QML 侧报 “module VLCQtQml is not installed”原因libVLCQtQml.dll.a 链接了但 QML 插件没有注册。VLC-Qt 的 QML 模块需要额外的 qmldir 和插件 DLL。解决确认压缩包里是否有 QML 插件目录。如果没有说明这个包只覆盖了 Core 和 Widgets 的 C 接口QML 需要另外处理。这种情况下要么改用 Widgets 方案要么自己补 QML 插件。5. 进阶验证用 CMake 的 imported target 属性反查依赖链5.1 查看 imported target 的实际属性CMake 配置成功后可以用cmake --build之前先打印 target 属性确认链接路径和 include 路径是否符合预期。在 CMakeLists.txt 里临时加get_target_property(CORE_INCLUDES VLCQt::Core INTERFACE_INCLUDE_DIRECTORIES) get_target_property(CORE_LIBS VLCQt::Core INTERFACE_LINK_LIBRARIES) message(STATUS VLCQt::Core includes: ${CORE_INCLUDES}) message(STATUS VLCQt::Core links: ${CORE_LIBS})逻辑说明INTERFACE_INCLUDE_DIRECTORIES告诉你头文件从哪来INTERFACE_LINK_LIBRARIES告诉你它还依赖谁。如果CORE_LIBS里出现了LibVLC::LibVLC之类的目标说明 Targets.cmake 用了 find_dependency你需要确保那个依赖也能被找到。参数说明get_target_property对 imported target 同样有效但属性名必须是 CMake 认可的。如果属性不存在会返回NOTFOUND不会报错。5.2 用 dumpbin 或 objdump 验证导入库符号MinGW 环境下可以用objdump -t libVLCQtCore.dll.a看导入库里的符号表。如果某个类的方法符号缺失说明这个导入库不完整或者版本不匹配。# 在 MinGW 的 bin 目录下执行 objdump -t D:/sdk/vlc-qt-install/lib/libVLCQtCore.dll.a | grep VlcMediaPlayer预期能看到__imp__ZN14VlcMediaPlayer...之类的符号。如果搜不到说明这个 .dll.a 里没有该类的导出链接时就会报 undefined reference。5.3 版本对齐检查表组件本包对应版本检查方式Qt5.15.2qmake -v 或 CMake 输出VLC3.0.14vlc --version 或 libvlc.dll 属性MinGW8.1.0_64gcc --versionVLC-Qt由包内 Targets 决定看 ConfigVersion.cmake如果 Qt 是 5.15.2 但 MinGW 是 7.3.0ABI 不兼容链接会报一堆undefined reference。这个包明确写了 mingw8.1.0_64就别用其他版本的工具链去试。5.4 一个我常犯的错误早期我图省事直接把.dll.a拖进 Qt Creator 的 LIBS 里结果 CMake 和 qmake 混用include 路径对不上编译报“找不到 VLCQtCore/MediaPlayer.h”。后来我强制自己只要用 CMake就老老实实 find_package target_link_libraries不手动写 LIBS。从那以后每次新建工程我都先跑一遍cmake -S . -B build -DCMAKE_PREFIX_PATH...确认配置阶段无警告再写业务代码。希望帮到你。本文还有配套的精品资源点击获取