Qt视频播放器核心难点在于绕过默认行为的坑：QMediaPlayer需显式调用setVideoOutput()才能出画，Windows常因Media Foundation解码器缺失致黑屏/静音，Linux依赖GStreamer插件，macOS易卡在LoadingMedia状态，缩放黑边需重写resizeEvent，Qt6中setSource()替代setMedia()且要求绝对路径。
Qt开发视频播放器客户端，核心不是“能不能做”，而是“怎么绕过默认行为的坑”。QMediaPlayer + QVideoWidget 看似开箱即用，但实际部署时大概率在 Windows 上静音、黑屏、缩放撕裂，Linux 上报 GStreamer not found，macOS 上卡在 QMediaStatus::LoadingMedia。这些问题不靠配置和代码顺序，根本跑不起来。
QMediaPlayer 初始化必须绑定 videoOutput 才能出画面
很多人写完 QMediaPlayer *player = new QMediaPlayer 就直接 setMedia()，结果 QVideoWidget 一直空白。原因很简单：QMediaPlayer 默认不输出视频帧，它只管解码调度；画面渲染完全依赖你显式指定 setVideoOutput()。
- 必须在
setMedia()之前或之后立即调用player->setVideoOutput(videoWidget)，且videoWidget不能是临时栈对象（要用new分配） - 如果用了
QMediaPlaylist，也要确保 playlist 的每个 media 都能被 video output 消费——player->setPlaylist(playlist)后仍需再调一次player->setVideoOutput(videoWidget) - QVideoWidget 默认不自动调整尺寸，记得调
videoWidget->setAspectRatioMode(Qt::KeepAspectRatio)，否则拉伸变形
Windows 下没声音/无法播放 MP4 的真实原因不是 Qt 版本
错误现象：QMediaPlayer::Error 信号触发，errorString() 返回空，或者播放时只有音频没画面、有画面没音频。这不是 Qt 写错了，而是系统级解码器链没接上。
- Qt6 默认后端是
mediafoundation，但 Windows 10/11 默认禁用旧版 Media Foundation 解码器，尤其对 H.264/H.265 容器支持不全 - 不要改
QT_MEDIA_BACKEND强切directshow（已废弃），而应安装 LAV Filters 并确保其路径加入PATH环境变量（如qputenv("PATH", "C:/LAVFilters;" + qgetenv("PATH"))） - MP4 文件若含 AAC-LC 音频 + H.264 视频一般能播；若含 E-AC3、DTS 或 HEVC Main10，QMediaPlayer 直接拒解——这不是 bug，是 Qt 官方明确不打包私有解码器
QVideoWidget 缩放时黑边/窗口重绘异常的修复点
拖动主窗口边缘缩放、切换全屏、甚至最小化再还原后，QVideoWidget 经常出现黑块、错位、残留残影。这不是 repaint() 没调好，而是底层 surface 生命周期没对齐。
- 必须重写
QVideoWidget::resizeEvent()，并在其中调updateGeometry()和repaint()，仅靠父布局 stretch 不生效 - 避免把
QVideoWidget套在QScrollArea或QGraphicsView里——它们会截断 native video surface 的绘制通道 - 在
QVideoWidget上叠加控件（如进度条、按钮）时，务必设setAttribute(Qt::WA_TransparentForMouseEvents, false)，否则鼠标穿透到视频层，拖拽失效
Qt6 中 setSource() 替代 setMedia() 但兼容性陷阱多
Qt6.5+ 废弃了 setMedia(QUrl)，改用 setSource(QUrl)。表面只是函数名变，实则行为差异极大：
-
setSource()要求 URL 必须是本地绝对路径（QUrl::fromLocalFile()），网络流地址（http://）需额外启用QT_FEATURE_multimedia_streaming并链接对应 backend - 若传入相对路径或非法 URL，
QMediaPlayer::MediaStatus会卡在NoMedia，且不发任何 error 信号——只能靠轮询mediaStatus()判断 - Qt6.7 开始，
QMediaPlaylist的addMedia()也强制要求QMediaContent，不能再直接塞QUrl，否则编译失败
真正难的从来不是写几行播放逻辑，而是确认当前运行环境的解码器链是否完整、video output 是否被父窗口遮挡、缩放事件有没有触发底层 surface 重建。这些细节不逐项验证，哪怕代码语法全对，播放器也只会安静地黑着屏。
