在Qt里做视频播放我第一个想到的就是QMediaPlayer。它属于Qt Multimedia模块把解码、音视频同步、播放控制这些底层事情全封装了你在代码里只需要给出一把文件路径加一个显示窗口就能把一个视频跑起来。这篇博客不是精讲源码而是从实操角度把QMediaPlayer从选型到落地、从踩坑到打包讲透适合刚开始接触Qt的开发者也适合需要在桌面客户端里快速集成视频播放能力的人。1. QMediaPlayer到底能干什么1.1 一个类解决“播放”这件事QMediaPlayer是Qt多媒体模块里的核心播放引擎它提供的是“媒体播放”层面的完整能力打开媒体源、播放、暂停、停止、拖拽进度、获取时长、查询播放状态、接收错误信息。它本身不直接渲染画面而是把解码后的视频帧交给输出目标去显示把音频交给输出设备去播放。这种分层设计让它在项目里的替换成本很低你今天用QVideoWidget显示明天想改成自定义渲染只需要换掉输出部分播放控制逻辑可以原封不动。很多人刚开始会把QMediaPlayer和QSoundEffect、QMediaPlaylist搞混。QSoundEffect只适合短音效播放是“一次性”的QMediaPlayer才是干重活的长音频、视频、流媒体都靠它。Qt 5里还有个QMediaPlaylist用来管理播放列表但Qt 6里这个类被移除了官方不再提供现成队列你得自己维护一个媒体列表播完一个再播下一个。这个改动影响挺大后面我会细说。说到线程QMediaPlayer内部已经用独立线程处理解码和渲染你在UI线程里调用它的接口、连接它的信号就行完全不需要自己开线程去“包一层”。不少新手一看到视频解码就想着用moveToThread实际上这是多余的QMediaPlayer从设计上就是异步的播放状态变化、进度更新都会通过信号回传到调用线程。你如果在子线程里new了QMediaPlayer反而要自己处理事件循环和线程生命周期纯属给自己找麻烦。1.2 核心API速览setSource(QUrl)设置媒体源Qt 6写法异步加载加载完成后自动开始播放如果调用了play。setMedia(QUrl)Qt 5写法在Qt 6里已废弃但仍能看到老项目大量使用。play()/pause()/stop()三兄弟最常用。stop之后position会归零。setPosition(qint64 ms)seek毫秒单位。duration()返回媒体总时长没加载完之前可能是0。setPlaybackRate(qreal)变速播放1.0是正常速度0.5是一倍慢放2.0是二倍快进声音也会变调。setVolume(int)音量0-100建议接在QAudioOutput上见后文。setNotifyInterval(int ms)设置positionChanged信号的发射频率默认1000ms调小可以更精细但代价是信号变频繁。errorOccurred信号播放出错时发射配合errorString()拿错误描述。mediaStatusChanged信号媒体加载状态变化比如Buffering、Loaded、EndOfMedia做复杂的加载提示会用上。这里重点说一下Qt 5和Qt 6在音频输出上的区别。Qt 6强制要求QMediaPlayer必须配置一个QAudioOutput对象才能出声你只调setVideoOutput是不会有声音的。Qt 5.15就没有这个限制setMedia之后就自动把音频送到默认输出设备。很多从Qt 5迁到Qt 6的朋友第一个碰到的“怪问题”就是画面正常、声音全无就是因为没new QAudioOutput并setAudioOutput。1.3 QMediaPlayer和QML的那点事用QWidget做桌面界面时播放视频一般就是QVideoWidget一嵌完事这是最朴素也最管用的方案。但如果你用的是QML/QuickQt还提供了VideoOutput类型配合QtMultimedia模块玩法更灵活比如把视频当纹理贴到3D模型上、做转场特效之类。场景图渲染效率确实高但有学习成本而且调试起来比Widgets麻烦。我觉得项目初期还是先把QWidgets方案跑通确认解码和显示链路没问题再考虑上Quick渲染避免一步跨太远踩进坑里出不来。2. 动手前先想清楚版本、输出方案和后端2.1 选哪个Qt版本真的很重要这个话题我多说几句。QMediaPlayer在Qt 5和Qt 6里的API差异不是修修补补而是动了根本的老的setMedia被换成了setSource老的隐式音频输出被换成了显式的QAudioOutput老的QMediaPlaylist直接被删掉了。这意味着你写代码前就必须确定目标版本否则写一半再迁工作量比你想象的大。维护老项目或者团队更熟悉Qt 5那守在5.15.2比较稳。这个版本是Qt 5系列的长期支持版本资料最多网上示例基本都能跑适合快速交差。新项目建议直接上Qt 6.8这类新版本。Qt 6的多媒体后端已经全面转向FFmpeg支持的格式更多API也更合理。但代价是你得在打包发布时额外带上FFmpeg的动态库体积会膨胀。后面我会专门讲发布时缺这缺那的问题。还要注意编译器套件的区别。MSVC 2019编译的Qt库只能用MSVC编译器去链MinGW编译的库只能用MinGW编译器去链。混用直接报错。比如你下了5.15.2_msvc2019_64的Qt包却在Qt Creator里用MinGW套件十有八九会遇到类似cannot find -lQt5Widgets或者:-1: error: dependent ..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets does not exist的编译错误。这不是代码问题是套件选择错了切回MSVC工具链就好了。2.2 视频输出方案要按场景选QMediaPlayer本身不负责画图像它只是把一帧一帧的视频数据送出去。你在界面上看到的画面其实是输出组件的功劳。常见输出方案有三种第一种QVideoWidget最简单几十行代码就能把视频嵌进普通Widget窗口。适合大多数桌面软件、播放器Demo、教学工具缺点是样式和交互受Widgets限制做不了花哨效果。它内部会处理窗口尺寸变化但如果你把视频塞进Canvas或透明窗口可能出现背景黑色无法透明的问题这是当前Widgets方案的一个已知局限。第二种QGraphicsVideoItem适合嵌在QGraphicsScene场景里可以做缩放、旋转适合做监控墙、多屏展示。它本质是在场景中绘制视频帧性能比QVideoWidget更可控。第三种自己拿QVideoFrame渲染。这种就是完全自定义了你通过QMediaPlayer的videoSink()拿到视频帧再用QOpenGLWidget把帧画成纹理。适合做鱼眼校正、滤镜、加字幕、特殊抠像这类高级需求。但你得自己处理像素格式转换YUV转RGB这一关就够折腾的。我遇到过一个需求是把视频画面实时旋转并叠加UI最后还是走了QOpenGLWidget自定义渲染因为QVideoWidget做不到旋转。2.3 后端决定你能播什么这里说的“后端”是Qt Multimedia在底层实际干活的解码库。不同平台、不同版本后端都不一样Windows Qt 5.15默认后端是Windows Media FoundationWMF能不能播取决于系统装了什么解码器。比如某些AV1、HEVC格式Win10没装扩展包就是放不出来。MVP格式没问题但MKV/FLV不一定都能识别。Linux Qt 5.15一般走GStreamer需要你本机装gstreamer开发库和插件。没装插件播放时可能直接没有画面或没有声音。Windows Qt 6.x新版本已经默认用FFmpeg后端。这个后端强大很多常见编码基本都能解但发布时要额外带上FFmpeg的dll以及Qt自带的media插件目录后面打包一节我会详细列。这些差异直接导致同一份代码在你自己电脑上跑得很欢发给客户就黑屏、报错、无声音。你写代码时心里要有这根弦播放不了先怀疑后端再怀疑自己代码。3. 从零搭一个带UI的播放器3.1 工程配置文件写法我用CMake给你演示。Qt 6建议CMakeQt 5也支持但老项目很多还是.pro qmake。CMake负责把Qt库和头文件找对最后靠Qt Creator的套件选择决定编译器。如果CMake找不到Qt多半是CMAKE_PREFIX_PATH没指向你的Qt安装目录。cmake_minimum_required(VERSION 3.16) project(QtPlayerDemo VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) find_package(Qt6 REQUIRED COMPONENTS Widgets Multimedia MultimediaWidgets) add_executable(QtPlayerDemo main.cpp ) target_link_libraries(QtPlayerDemo PRIVATE Qt6::Widgets Qt6::Multimedia Qt6::MultimediaWidgets )Qt 5就用find_package(Qt5 REQUIRED COMPONENTS Widgets Multimedia MultimediaWidgets)链接库名换成Qt5::Multimedia和Qt5::MultimediaWidgets。需要注意一下QVideoWidget位于MultimediaWidgets模块很多人只link了Widgets和Multimedia结果编译时找不到QVideoWidget头文件报错半天才反应过来。3.2 UI布局与设计我做的播放器窗口很朴素上面一个视频显示区下面一行按钮再下面一个进度条。核心思路是“能跑起来方便扩展”所以信号连接写得直白方便你改成自己的界面。布局上要注意视频Widget放进布局器窗口拉伸时才不会变形。进度条的setRange和setValue都是在信号里动态更新千万不要在初始化时写死。3.3 完整代码示例Qt 6写法#include QApplication #include QMainWindow #include QMediaPlayer #include QAudioOutput #include QVideoWidget #include QPushButton #include QSlider #include QVBoxLayout #include QHBoxLayout #include QFileDialog #include QLabel #include QUrl int main(int argc, char *argv[]) { QApplication app(argc, argv); QMainWindow window; window.setWindowTitle(QMediaPlayer 播放器 Demo); QWidget *central new QWidget(window); QVBoxLayout *layout new QVBoxLayout(central); QVideoWidget *videoWidget new QVideoWidget; videoWidget-setMinimumSize(640, 360); QMediaPlayer player; QAudioOutput audioOutput; player.setAudioOutput(audioOutput); player.setVideoOutput(videoWidget); QPushButton *openBtn new QPushButton(打开文件); QPushButton *playBtn new QPushButton(播放/暂停); QSlider *slider new QSlider(Qt::Horizontal); QLabel *posLabel new QLabel(00:00 / 00:00); QHBoxLayout *btnLayout new QHBoxLayout; btnLayout-addWidget(openBtn); btnLayout-addWidget(playBtn); btnLayout-addWidget(slider); btnLayout-addWidget(posLabel); layout-addWidget(videoWidget, 1); layout-addLayout(btnLayout); window.setCentralWidget(central); QObject::connect(openBtn, QPushButton::clicked, []() { QString filePath QFileDialog::getOpenFileName( window, 选择视频文件, QString(), 视频文件 (*.mp4 *.avi *.mkv *.mov *.wmv);;所有文件 (*.*)); if (filePath.isEmpty()) { return; } player.setSource(QUrl::fromLocalFile(filePath)); player.play(); }); QObject::connect(playBtn, QPushButton::clicked, []() { if (player.playbackState() QMediaPlayer::PlayingState) { player.pause(); } else { player.play(); } }); QObject::connect(player, QMediaPlayer::durationChanged, slider, QSlider::setRange); // durationChanged 参数是 qint64slider::setRange 有两个重载这里要注意 QObject::connect(player, QMediaPlayer::positionChanged, [](qint64 pos) { slider-setValue(static_castint(pos)); if (player.duration() 0) { qint64 total player.duration(); posLabel-setText(QString(%1:%2 / %3:%4) .arg(pos / 60000).arg(pos % 60000 / 1000, 2, 10, QLatin1Char(0)) .arg(total / 60000).arg(total % 60000 / 1000, 2, 10, QLatin1Char(0))); } }); QObject::connect(slider, QSlider::sliderMoved, [](int value) { player.setPosition(static_castqint64(value)); }); QObject::connect(player, QMediaPlayer::errorOccurred, [](QMediaPlayer::Error error, const QString errorString) { Q_UNUSED(error); window.setWindowTitle(播放错误 errorString); }); window.resize(900, 560); window.show(); return app.exec(); }这段代码有几个值得强调的点QUrl::fromLocalFile(filePath)这个一定要用直接player.setSource(QUrl(filePath))在Windows上会解析不出file scheme导致文件打不开。中文路径和空格都不怕fromLocalFile会帮你处理好。setRange槽函数重载问题slider-setRange有(int, int)和(int)两个重载而durationChanged发的是qint64直接用槽连接经常编译报错。我在上面用lambda绕开了。新手容易在这卡住原因就是返回类型和重载不匹配。Q_UNUSED(error)编译器不会warning但代码能跑。实际项目里你应该把error和errorString都打日志方便排查。3.4 Qt 5.15的写法差异Qt 5的项目把上面代码改成这样就行核心区别就是去掉QAudioOutput换回setMedia// Qt 5.15 #include QMediaPlayer #include QVideoWidget QMediaPlayer player; player.setMedia(QUrl::fromLocalFile(filePath)); player.setVideoOutput(videoWidget); player.play(); // 没有 setAudioOutput也没有 errorOccurred 里的一些错误码改用 error 成员函数声音会自动走系统默认设备不用你管。Qt 5里查询错误用error()函数和errorString()而不是errorOccurred信号。这一点迁移时特别容易改漏。3.5 进度条和状态同步别图省事我在项目里踩过这样一个坑进度条直接用slider-setRange(0, duration)拖动时也是setPosition看起来没问题但用户拖拽途中positionChanged不断发射滑块容易被拽回去手指一松又跳回原位。这个问题在播放流畅的视频时特别明显滑块像抽搐一样。标准做法是加一个bool sliderPressed false的状态位。按下进度条时置true拖动期间在setPosition槽函数里不做更新松开后再置false。上面示例代码为简洁起见没写但你自己做产品时一定要加上。另外positionChanged默认频率是每秒1次做桌面播放器时太糙进度条看起来一顿一顿的。可以在初始化时加一句player.setNotifyInterval(200)200毫秒刷新一次手感明显顺滑。注意不要调太低否则信号风暴会让UI卡顿。4. 避坑实录让我半夜改代码的问题4.1 “qpa.plugin could not find the windows platform plugin”是怎么回事这个报错相信不少人都见过尤其是把exe单独拷出来直接双击运行的时候。原始报错长这样qt.qpa.plugin: could not find the qt platform plugin windows in This application failed to start because no Qt platform plugin could be initialized.这通常不是代码问题是运行时找不到Qt的平台插件qwindows.dll。Qt程序启动时QPA层需要加载platforms目录下的插件而你的exe旁边没有platforms目录Qt也不知道去Qt安装目录找于是直接退出了。解决办法三种按推荐程度排序第一不要手动拷用官方部署工具windeployqt.exe。你在Qt命令行里执行windeployqt.exe 你的程序.exe它会自动把exe需要的dll、plugins、翻译文件全部放到exe同级目录。生成后你能看到一个platforms文件夹里面躺着qwindows.dll。这个工具在Qt 5和Qt 6里都有只是新版本还会额外拉进来更多多媒体后端文件。第二临时调试时在程序运行前手动设置环境变量set QT_QPA_PLATFORM_PLUGIN_PATHD:\Qt\6.8.3\msvc2022_64\plugins\platforms这样能救命但治标不治本。第三发布给客户时把exe、platforms、整个多媒体插件目录、依赖dll打成一个文件夹打包安装程序时一起带上。反正记住一句话不要只发exe要发“装载了运行时的文件夹”。4.2 编译错误 dependent ... does not exist这个坑很多新手会碰到报错类似:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets does not exist.点进去看到qtwidgets都认识路径却像鬼一样怎么都找不到。核心原因就是Qt Creator的工具链和Qt库不匹配。比如你打开一个Qt 6的项目却指定了Qt 5.15.2的Kit或者MSVC项目用MinGW去编译。Qt Creator在生成Makefile时会记录Qt库的绝对路径路径对不上编译就挂。解决思路很简单项目构建前在Qt Creator的“工具 选项 Kits”里检查一下Kits编译器是MSVC还是MinGW、Qt版本路径是否存在、CMake/Qmake是否齐全。如果项目是拷贝来的直接删掉build目录和CMakeCache.txt重新构建让Qt Creator自动探测。如果你要用VS直接编译需要确认环境变量里QTDIR指向正确版本并且VS的扩展(Qt VS Tools)配置了对应的Qt Version。这类破事90%是“开发环境不干净”造成的重新检查一遍Kit比改代码有用得多。4.3 有声音没画面或者黑屏视频播放时有声音但黑屏是最常见的播放器Bug。优先排查顺序第一有没有设置视频输出。player.setVideoOutput(videoWidget)漏了那画面当然不会显示但音频还是会播放所以听得到声音看不到人。第二QVideoWidget有没有被显示出来。很多人把videoWidget创建出来了但忘了addWidget到布局等于窗口里根本看不到这个控件。音频正常画面还是黑。第三后端解码不出视频流。某些格式音频解码成功、视频解码失败也会出现“只有声音没有画面”。这种看Qt日志或者errorString()能看出端倪。Qt 6的FFmpeg后端对视频编解码支持很全但如果你还在Qt 5 Windows Media Foundation遇到H.264高码率文件可能就黑屏。第四如果视频显示区是黑底但视频实际在播放检查一下窗口的paintEvent重写是否干扰了QVideoWidget。别给videoWidget设置透明背景也别把它塞进带WA_OpaquePaintEvent的自绘容器里。4.4 文件路径和URL格式问题用QMediaPlayer播放本地文件路径必须转成QUrl::fromLocalFile()这一点再强调一次。直接用QUrl(C:/video/xxx.mp4)会解析成URL scheme是C:的诡异协议Qt根本不认。用QUrl::fromLocalFile(C:\\video\\xxx.mp4)得到的地址是file:///C:/video/xxx.mp4这才是Qt认识的本地文件地址。还有一个容易被忽略的坑Windows下路径分隔符是反斜杠但在C字符串里写反斜杠要转义很容易写成C:\video\test.mp4导致路径错了。用正斜杠C:/video/test.mp4在Qt里完全能用省心。如果你是把路径写死在配置文件里一定要让程序启动时打印出来看一眼别在字符串转义这一层埋雷。4.5 打包发布时到底要带哪些文件手动复制文件打包QPMediaPlayer应用比你想的要复杂。老老实实跑一遍windeployqt然后再检查多媒体插件。以Qt 6.8为例发布目录应该包含你的exeplatforms/qwindows.dllmediaservice/ffmpeg目录Qt 6多媒体后端负责解封装和解码imageformats如果需要显示图片格式Qt6Core.dll、Qt6Gui.dll、Qt6Widgets.dll、Qt6Multimedia.dll、Qt6Network.dllQt6Multimedia依赖网络模块FFmpeg相关的dlllibavcodec、libavformat、libavutil、libswscale、libswresample具体文件名看版本如果你还用了QAudioOutput可能还需要Qt6MultimediaWidgets.dll发布后第一时间在没有装Qt的机器上跑一遍能启动、能播视频才算完整。我见过windeployqt跑完程序能启动但播放视频就报Cannot load FFmpeg的情况因为FFmpeg的dll没拷全或者路径不对。这时候把FFmpeg dll放在exe同级目录并且保证Windows能找到就正常了。5. 高频问题速查表现象可能原因解决方案程序双击后弹窗“could not find windows platform plugin”缺少platforms/qwindows.dll或QT_QPA_PLATFORM_PLUGIN_PATH不对用windeployqt部署或手动补platforms目录编译报dependent ...include\qtwidgets does not existQt Creator Kit工具链与Qt库版本不匹配检查Kit选对MSVC/MinGW和Qt版本清理构建目录有声音但黑屏setVideoOutput漏了QVideoWidget没加入布局在play前设置player.setVideoOutput(videoWidget)无声但有画面Qt 6里没设置QAudioOutputQAudioOutput *output new QAudioOutput; player.setAudioOutput(output);播放不了MKV或某些视频Windows Media Foundation后端不支持或系统缺解码器Qt 5下换FFmpeg后端升级到Qt 6或按装对应解码器拖动进度条时滑块乱跳positionChanged和sliderMoved互相冲突加pressed标志位拖动期间不响应positionChanged打开文件后没反应路径未用QUrl::fromLocalFile或使用了不存在的路径改为player.setSource(QUrl::fromLocalFile(filePath))发布到未装Qt的电脑上启动崩溃缺dll、缺插件、缺FFmpeg用windeployqt确认FFmpeg dll在exe同级检查plugins目录Qt 5迁移Qt 6后编译不过setMedia/setAudioOutput/playlist API差异改setSource、引入QAudioOutput去掉QMediaPlaylist视频播放一闪而过状态直接EndOfMedia源文件损坏或解码器不支持查看errorString换一个格式的测试文件确认最后说一个我自己的小习惯调试QMediaPlayer时我会把errorOccurred和mediaStatusChanged都连着打日志不轻易相信“代码看着没问题”。很多所谓“Qt播放器怪毛病”最后都是格式、插件、路径这些边缘问题。你先确认运行环境干净再怀疑自己的播放逻辑。如果你只是临时做一个工具用QMediaPlayer火力全开。如果你要做的播放器对格式兼容性要求很高比如直播流、硬解、自定义滤镜那我建议你在项目初期就考虑自研解码管线或者引入现成的播放框架。QMediaPlayer是捷径但懂原理、懂报错、懂打包这个捷径才走得稳。 
长河君 · 2026/10/9 12:51:09 · 阅读 1.2k Qt QMediaPlayer视频播放实战：从API调用到发布打包
在Qt里做视频播放我第一个想到的就是QMediaPlayer。它属于Qt Multimedia模块把解码、音视频同步、播放控制这些底层事情全封装了你在代码里只需要给出一把文件路径加一个显示窗口就能把一个视频跑起来。这篇博客不是精讲源码而是从实操角度把QMediaPlayer从选型到落地、从踩坑到打包讲透适合刚开始接触Qt的开发者也适合需要在桌面客户端里快速集成视频播放能力的人。1. QMediaPlayer到底能干什么1.1 一个类解决“播放”这件事QMediaPlayer是Qt多媒体模块里的核心播放引擎它提供的是“媒体播放”层面的完整能力打开媒体源、播放、暂停、停止、拖拽进度、获取时长、查询播放状态、接收错误信息。它本身不直接渲染画面而是把解码后的视频帧交给输出目标去显示把音频交给输出设备去播放。这种分层设计让它在项目里的替换成本很低你今天用QVideoWidget显示明天想改成自定义渲染只需要换掉输出部分播放控制逻辑可以原封不动。很多人刚开始会把QMediaPlayer和QSoundEffect、QMediaPlaylist搞混。QSoundEffect只适合短音效播放是“一次性”的QMediaPlayer才是干重活的长音频、视频、流媒体都靠它。Qt 5里还有个QMediaPlaylist用来管理播放列表但Qt 6里这个类被移除了官方不再提供现成队列你得自己维护一个媒体列表播完一个再播下一个。这个改动影响挺大后面我会细说。说到线程QMediaPlayer内部已经用独立线程处理解码和渲染你在UI线程里调用它的接口、连接它的信号就行完全不需要自己开线程去“包一层”。不少新手一看到视频解码就想着用moveToThread实际上这是多余的QMediaPlayer从设计上就是异步的播放状态变化、进度更新都会通过信号回传到调用线程。你如果在子线程里new了QMediaPlayer反而要自己处理事件循环和线程生命周期纯属给自己找麻烦。1.2 核心API速览setSource(QUrl)设置媒体源Qt 6写法异步加载加载完成后自动开始播放如果调用了play。setMedia(QUrl)Qt 5写法在Qt 6里已废弃但仍能看到老项目大量使用。play()/pause()/stop()三兄弟最常用。stop之后position会归零。setPosition(qint64 ms)seek毫秒单位。duration()返回媒体总时长没加载完之前可能是0。setPlaybackRate(qreal)变速播放1.0是正常速度0.5是一倍慢放2.0是二倍快进声音也会变调。setVolume(int)音量0-100建议接在QAudioOutput上见后文。setNotifyInterval(int ms)设置positionChanged信号的发射频率默认1000ms调小可以更精细但代价是信号变频繁。errorOccurred信号播放出错时发射配合errorString()拿错误描述。mediaStatusChanged信号媒体加载状态变化比如Buffering、Loaded、EndOfMedia做复杂的加载提示会用上。这里重点说一下Qt 5和Qt 6在音频输出上的区别。Qt 6强制要求QMediaPlayer必须配置一个QAudioOutput对象才能出声你只调setVideoOutput是不会有声音的。Qt 5.15就没有这个限制setMedia之后就自动把音频送到默认输出设备。很多从Qt 5迁到Qt 6的朋友第一个碰到的“怪问题”就是画面正常、声音全无就是因为没new QAudioOutput并setAudioOutput。1.3 QMediaPlayer和QML的那点事用QWidget做桌面界面时播放视频一般就是QVideoWidget一嵌完事这是最朴素也最管用的方案。但如果你用的是QML/QuickQt还提供了VideoOutput类型配合QtMultimedia模块玩法更灵活比如把视频当纹理贴到3D模型上、做转场特效之类。场景图渲染效率确实高但有学习成本而且调试起来比Widgets麻烦。我觉得项目初期还是先把QWidgets方案跑通确认解码和显示链路没问题再考虑上Quick渲染避免一步跨太远踩进坑里出不来。2. 动手前先想清楚版本、输出方案和后端2.1 选哪个Qt版本真的很重要这个话题我多说几句。QMediaPlayer在Qt 5和Qt 6里的API差异不是修修补补而是动了根本的老的setMedia被换成了setSource老的隐式音频输出被换成了显式的QAudioOutput老的QMediaPlaylist直接被删掉了。这意味着你写代码前就必须确定目标版本否则写一半再迁工作量比你想象的大。维护老项目或者团队更熟悉Qt 5那守在5.15.2比较稳。这个版本是Qt 5系列的长期支持版本资料最多网上示例基本都能跑适合快速交差。新项目建议直接上Qt 6.8这类新版本。Qt 6的多媒体后端已经全面转向FFmpeg支持的格式更多API也更合理。但代价是你得在打包发布时额外带上FFmpeg的动态库体积会膨胀。后面我会专门讲发布时缺这缺那的问题。还要注意编译器套件的区别。MSVC 2019编译的Qt库只能用MSVC编译器去链MinGW编译的库只能用MinGW编译器去链。混用直接报错。比如你下了5.15.2_msvc2019_64的Qt包却在Qt Creator里用MinGW套件十有八九会遇到类似cannot find -lQt5Widgets或者:-1: error: dependent ..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets does not exist的编译错误。这不是代码问题是套件选择错了切回MSVC工具链就好了。2.2 视频输出方案要按场景选QMediaPlayer本身不负责画图像它只是把一帧一帧的视频数据送出去。你在界面上看到的画面其实是输出组件的功劳。常见输出方案有三种第一种QVideoWidget最简单几十行代码就能把视频嵌进普通Widget窗口。适合大多数桌面软件、播放器Demo、教学工具缺点是样式和交互受Widgets限制做不了花哨效果。它内部会处理窗口尺寸变化但如果你把视频塞进Canvas或透明窗口可能出现背景黑色无法透明的问题这是当前Widgets方案的一个已知局限。第二种QGraphicsVideoItem适合嵌在QGraphicsScene场景里可以做缩放、旋转适合做监控墙、多屏展示。它本质是在场景中绘制视频帧性能比QVideoWidget更可控。第三种自己拿QVideoFrame渲染。这种就是完全自定义了你通过QMediaPlayer的videoSink()拿到视频帧再用QOpenGLWidget把帧画成纹理。适合做鱼眼校正、滤镜、加字幕、特殊抠像这类高级需求。但你得自己处理像素格式转换YUV转RGB这一关就够折腾的。我遇到过一个需求是把视频画面实时旋转并叠加UI最后还是走了QOpenGLWidget自定义渲染因为QVideoWidget做不到旋转。2.3 后端决定你能播什么这里说的“后端”是Qt Multimedia在底层实际干活的解码库。不同平台、不同版本后端都不一样Windows Qt 5.15默认后端是Windows Media FoundationWMF能不能播取决于系统装了什么解码器。比如某些AV1、HEVC格式Win10没装扩展包就是放不出来。MVP格式没问题但MKV/FLV不一定都能识别。Linux Qt 5.15一般走GStreamer需要你本机装gstreamer开发库和插件。没装插件播放时可能直接没有画面或没有声音。Windows Qt 6.x新版本已经默认用FFmpeg后端。这个后端强大很多常见编码基本都能解但发布时要额外带上FFmpeg的dll以及Qt自带的media插件目录后面打包一节我会详细列。这些差异直接导致同一份代码在你自己电脑上跑得很欢发给客户就黑屏、报错、无声音。你写代码时心里要有这根弦播放不了先怀疑后端再怀疑自己代码。3. 从零搭一个带UI的播放器3.1 工程配置文件写法我用CMake给你演示。Qt 6建议CMakeQt 5也支持但老项目很多还是.pro qmake。CMake负责把Qt库和头文件找对最后靠Qt Creator的套件选择决定编译器。如果CMake找不到Qt多半是CMAKE_PREFIX_PATH没指向你的Qt安装目录。cmake_minimum_required(VERSION 3.16) project(QtPlayerDemo VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) find_package(Qt6 REQUIRED COMPONENTS Widgets Multimedia MultimediaWidgets) add_executable(QtPlayerDemo main.cpp ) target_link_libraries(QtPlayerDemo PRIVATE Qt6::Widgets Qt6::Multimedia Qt6::MultimediaWidgets )Qt 5就用find_package(Qt5 REQUIRED COMPONENTS Widgets Multimedia MultimediaWidgets)链接库名换成Qt5::Multimedia和Qt5::MultimediaWidgets。需要注意一下QVideoWidget位于MultimediaWidgets模块很多人只link了Widgets和Multimedia结果编译时找不到QVideoWidget头文件报错半天才反应过来。3.2 UI布局与设计我做的播放器窗口很朴素上面一个视频显示区下面一行按钮再下面一个进度条。核心思路是“能跑起来方便扩展”所以信号连接写得直白方便你改成自己的界面。布局上要注意视频Widget放进布局器窗口拉伸时才不会变形。进度条的setRange和setValue都是在信号里动态更新千万不要在初始化时写死。3.3 完整代码示例Qt 6写法#include QApplication #include QMainWindow #include QMediaPlayer #include QAudioOutput #include QVideoWidget #include QPushButton #include QSlider #include QVBoxLayout #include QHBoxLayout #include QFileDialog #include QLabel #include QUrl int main(int argc, char *argv[]) { QApplication app(argc, argv); QMainWindow window; window.setWindowTitle(QMediaPlayer 播放器 Demo); QWidget *central new QWidget(window); QVBoxLayout *layout new QVBoxLayout(central); QVideoWidget *videoWidget new QVideoWidget; videoWidget-setMinimumSize(640, 360); QMediaPlayer player; QAudioOutput audioOutput; player.setAudioOutput(audioOutput); player.setVideoOutput(videoWidget); QPushButton *openBtn new QPushButton(打开文件); QPushButton *playBtn new QPushButton(播放/暂停); QSlider *slider new QSlider(Qt::Horizontal); QLabel *posLabel new QLabel(00:00 / 00:00); QHBoxLayout *btnLayout new QHBoxLayout; btnLayout-addWidget(openBtn); btnLayout-addWidget(playBtn); btnLayout-addWidget(slider); btnLayout-addWidget(posLabel); layout-addWidget(videoWidget, 1); layout-addLayout(btnLayout); window.setCentralWidget(central); QObject::connect(openBtn, QPushButton::clicked, []() { QString filePath QFileDialog::getOpenFileName( window, 选择视频文件, QString(), 视频文件 (*.mp4 *.avi *.mkv *.mov *.wmv);;所有文件 (*.*)); if (filePath.isEmpty()) { return; } player.setSource(QUrl::fromLocalFile(filePath)); player.play(); }); QObject::connect(playBtn, QPushButton::clicked, []() { if (player.playbackState() QMediaPlayer::PlayingState) { player.pause(); } else { player.play(); } }); QObject::connect(player, QMediaPlayer::durationChanged, slider, QSlider::setRange); // durationChanged 参数是 qint64slider::setRange 有两个重载这里要注意 QObject::connect(player, QMediaPlayer::positionChanged, [](qint64 pos) { slider-setValue(static_castint(pos)); if (player.duration() 0) { qint64 total player.duration(); posLabel-setText(QString(%1:%2 / %3:%4) .arg(pos / 60000).arg(pos % 60000 / 1000, 2, 10, QLatin1Char(0)) .arg(total / 60000).arg(total % 60000 / 1000, 2, 10, QLatin1Char(0))); } }); QObject::connect(slider, QSlider::sliderMoved, [](int value) { player.setPosition(static_castqint64(value)); }); QObject::connect(player, QMediaPlayer::errorOccurred, [](QMediaPlayer::Error error, const QString errorString) { Q_UNUSED(error); window.setWindowTitle(播放错误 errorString); }); window.resize(900, 560); window.show(); return app.exec(); }这段代码有几个值得强调的点QUrl::fromLocalFile(filePath)这个一定要用直接player.setSource(QUrl(filePath))在Windows上会解析不出file scheme导致文件打不开。中文路径和空格都不怕fromLocalFile会帮你处理好。setRange槽函数重载问题slider-setRange有(int, int)和(int)两个重载而durationChanged发的是qint64直接用槽连接经常编译报错。我在上面用lambda绕开了。新手容易在这卡住原因就是返回类型和重载不匹配。Q_UNUSED(error)编译器不会warning但代码能跑。实际项目里你应该把error和errorString都打日志方便排查。3.4 Qt 5.15的写法差异Qt 5的项目把上面代码改成这样就行核心区别就是去掉QAudioOutput换回setMedia// Qt 5.15 #include QMediaPlayer #include QVideoWidget QMediaPlayer player; player.setMedia(QUrl::fromLocalFile(filePath)); player.setVideoOutput(videoWidget); player.play(); // 没有 setAudioOutput也没有 errorOccurred 里的一些错误码改用 error 成员函数声音会自动走系统默认设备不用你管。Qt 5里查询错误用error()函数和errorString()而不是errorOccurred信号。这一点迁移时特别容易改漏。3.5 进度条和状态同步别图省事我在项目里踩过这样一个坑进度条直接用slider-setRange(0, duration)拖动时也是setPosition看起来没问题但用户拖拽途中positionChanged不断发射滑块容易被拽回去手指一松又跳回原位。这个问题在播放流畅的视频时特别明显滑块像抽搐一样。标准做法是加一个bool sliderPressed false的状态位。按下进度条时置true拖动期间在setPosition槽函数里不做更新松开后再置false。上面示例代码为简洁起见没写但你自己做产品时一定要加上。另外positionChanged默认频率是每秒1次做桌面播放器时太糙进度条看起来一顿一顿的。可以在初始化时加一句player.setNotifyInterval(200)200毫秒刷新一次手感明显顺滑。注意不要调太低否则信号风暴会让UI卡顿。4. 避坑实录让我半夜改代码的问题4.1 “qpa.plugin could not find the windows platform plugin”是怎么回事这个报错相信不少人都见过尤其是把exe单独拷出来直接双击运行的时候。原始报错长这样qt.qpa.plugin: could not find the qt platform plugin windows in This application failed to start because no Qt platform plugin could be initialized.这通常不是代码问题是运行时找不到Qt的平台插件qwindows.dll。Qt程序启动时QPA层需要加载platforms目录下的插件而你的exe旁边没有platforms目录Qt也不知道去Qt安装目录找于是直接退出了。解决办法三种按推荐程度排序第一不要手动拷用官方部署工具windeployqt.exe。你在Qt命令行里执行windeployqt.exe 你的程序.exe它会自动把exe需要的dll、plugins、翻译文件全部放到exe同级目录。生成后你能看到一个platforms文件夹里面躺着qwindows.dll。这个工具在Qt 5和Qt 6里都有只是新版本还会额外拉进来更多多媒体后端文件。第二临时调试时在程序运行前手动设置环境变量set QT_QPA_PLATFORM_PLUGIN_PATHD:\Qt\6.8.3\msvc2022_64\plugins\platforms这样能救命但治标不治本。第三发布给客户时把exe、platforms、整个多媒体插件目录、依赖dll打成一个文件夹打包安装程序时一起带上。反正记住一句话不要只发exe要发“装载了运行时的文件夹”。4.2 编译错误 dependent ... does not exist这个坑很多新手会碰到报错类似:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets does not exist.点进去看到qtwidgets都认识路径却像鬼一样怎么都找不到。核心原因就是Qt Creator的工具链和Qt库不匹配。比如你打开一个Qt 6的项目却指定了Qt 5.15.2的Kit或者MSVC项目用MinGW去编译。Qt Creator在生成Makefile时会记录Qt库的绝对路径路径对不上编译就挂。解决思路很简单项目构建前在Qt Creator的“工具 选项 Kits”里检查一下Kits编译器是MSVC还是MinGW、Qt版本路径是否存在、CMake/Qmake是否齐全。如果项目是拷贝来的直接删掉build目录和CMakeCache.txt重新构建让Qt Creator自动探测。如果你要用VS直接编译需要确认环境变量里QTDIR指向正确版本并且VS的扩展(Qt VS Tools)配置了对应的Qt Version。这类破事90%是“开发环境不干净”造成的重新检查一遍Kit比改代码有用得多。4.3 有声音没画面或者黑屏视频播放时有声音但黑屏是最常见的播放器Bug。优先排查顺序第一有没有设置视频输出。player.setVideoOutput(videoWidget)漏了那画面当然不会显示但音频还是会播放所以听得到声音看不到人。第二QVideoWidget有没有被显示出来。很多人把videoWidget创建出来了但忘了addWidget到布局等于窗口里根本看不到这个控件。音频正常画面还是黑。第三后端解码不出视频流。某些格式音频解码成功、视频解码失败也会出现“只有声音没有画面”。这种看Qt日志或者errorString()能看出端倪。Qt 6的FFmpeg后端对视频编解码支持很全但如果你还在Qt 5 Windows Media Foundation遇到H.264高码率文件可能就黑屏。第四如果视频显示区是黑底但视频实际在播放检查一下窗口的paintEvent重写是否干扰了QVideoWidget。别给videoWidget设置透明背景也别把它塞进带WA_OpaquePaintEvent的自绘容器里。4.4 文件路径和URL格式问题用QMediaPlayer播放本地文件路径必须转成QUrl::fromLocalFile()这一点再强调一次。直接用QUrl(C:/video/xxx.mp4)会解析成URL scheme是C:的诡异协议Qt根本不认。用QUrl::fromLocalFile(C:\\video\\xxx.mp4)得到的地址是file:///C:/video/xxx.mp4这才是Qt认识的本地文件地址。还有一个容易被忽略的坑Windows下路径分隔符是反斜杠但在C字符串里写反斜杠要转义很容易写成C:\video\test.mp4导致路径错了。用正斜杠C:/video/test.mp4在Qt里完全能用省心。如果你是把路径写死在配置文件里一定要让程序启动时打印出来看一眼别在字符串转义这一层埋雷。4.5 打包发布时到底要带哪些文件手动复制文件打包QPMediaPlayer应用比你想的要复杂。老老实实跑一遍windeployqt然后再检查多媒体插件。以Qt 6.8为例发布目录应该包含你的exeplatforms/qwindows.dllmediaservice/ffmpeg目录Qt 6多媒体后端负责解封装和解码imageformats如果需要显示图片格式Qt6Core.dll、Qt6Gui.dll、Qt6Widgets.dll、Qt6Multimedia.dll、Qt6Network.dllQt6Multimedia依赖网络模块FFmpeg相关的dlllibavcodec、libavformat、libavutil、libswscale、libswresample具体文件名看版本如果你还用了QAudioOutput可能还需要Qt6MultimediaWidgets.dll发布后第一时间在没有装Qt的机器上跑一遍能启动、能播视频才算完整。我见过windeployqt跑完程序能启动但播放视频就报Cannot load FFmpeg的情况因为FFmpeg的dll没拷全或者路径不对。这时候把FFmpeg dll放在exe同级目录并且保证Windows能找到就正常了。5. 高频问题速查表现象可能原因解决方案程序双击后弹窗“could not find windows platform plugin”缺少platforms/qwindows.dll或QT_QPA_PLATFORM_PLUGIN_PATH不对用windeployqt部署或手动补platforms目录编译报dependent ...include\qtwidgets does not existQt Creator Kit工具链与Qt库版本不匹配检查Kit选对MSVC/MinGW和Qt版本清理构建目录有声音但黑屏setVideoOutput漏了QVideoWidget没加入布局在play前设置player.setVideoOutput(videoWidget)无声但有画面Qt 6里没设置QAudioOutputQAudioOutput *output new QAudioOutput; player.setAudioOutput(output);播放不了MKV或某些视频Windows Media Foundation后端不支持或系统缺解码器Qt 5下换FFmpeg后端升级到Qt 6或按装对应解码器拖动进度条时滑块乱跳positionChanged和sliderMoved互相冲突加pressed标志位拖动期间不响应positionChanged打开文件后没反应路径未用QUrl::fromLocalFile或使用了不存在的路径改为player.setSource(QUrl::fromLocalFile(filePath))发布到未装Qt的电脑上启动崩溃缺dll、缺插件、缺FFmpeg用windeployqt确认FFmpeg dll在exe同级检查plugins目录Qt 5迁移Qt 6后编译不过setMedia/setAudioOutput/playlist API差异改setSource、引入QAudioOutput去掉QMediaPlaylist视频播放一闪而过状态直接EndOfMedia源文件损坏或解码器不支持查看errorString换一个格式的测试文件确认最后说一个我自己的小习惯调试QMediaPlayer时我会把errorOccurred和mediaStatusChanged都连着打日志不轻易相信“代码看着没问题”。很多所谓“Qt播放器怪毛病”最后都是格式、插件、路径这些边缘问题。你先确认运行环境干净再怀疑自己的播放逻辑。如果你只是临时做一个工具用QMediaPlayer火力全开。如果你要做的播放器对格式兼容性要求很高比如直播流、硬解、自定义滤镜那我建议你在项目初期就考虑自研解码管线或者引入现成的播放框架。QMediaPlayer是捷径但懂原理、懂报错、懂打包这个捷径才走得稳。