简介一套基于Qt框架调用摄像头的入门工程示例面向初学Qt多媒体模块的开发者演示如何通过QCamera选择设备、初始化预览、并在QLabel中实时显示捕获画面。工程共5个文件包含两个cpp源代码主要逻辑与入口、一个h头文件、一个ui界面设计文件及一个pro工程配置压缩包仅2KB代码量精简但基础模块完整便于快速读懂核心流程。项目源码中实现了摄像头状态监听、从取景器抓取帧并缩放显示到QLabel同时给出析构时停止设备的管理方式可直接在Qt环境中打开pro文件运行验证。已有5606人学习积累适合想要快速理解QCamera与QLabel配合用法、体验摄像头调用全流程的开发者参考也可作为后续实现视频录制或图像处理功能的起点。 做 Qt 开发久了几乎每个人都会碰到一个需求调摄像头。我最早是在一个设备巡检项目里用 QCamera 做扫码和拍照后来又在人脸识别门禁端上用过它。QCamera 是 Qt Multimedia 模块里专门负责摄像头采集的类配合 QCameraInfo、QCameraImageCapture、QMediaRecorder 这些兄弟类可以实现设备枚举、实时预览、拍照、录像、参数设置等一整套功能。这篇文章我会把 Qt 5 / Qt 6 两套写法都说清楚再把踩过的坑整理出来给正准备接摄像头的同学一份可以直接抄的作业。1. 环境准备先把多媒体模块跑起来1.1 工程配置里的三个关键点QCamera 不是 Qt 核心模块使用前必须把 multimedia 模块加进工程。这里有个容易搞混的点Qt 5 和 Qt 6 的模块划分不一样配置代码也不同。Qt 5 的 .pro 文件里这样写QT core gui multimedia multimediawidgetsQt 5 时代摄像头画面显示依赖QCameraViewfinder这个类在multimediawidgets模块里所以如果你只加multimedia编译时会出现找不到 QCameraViewfinder这种莫名其妙的报错实际原因就是模块没加全。到了 Qt 6multimediawidgets 被合并进了 multimedia 模块所以只需要QT core gui multimedia如果你用的是 CMake则是这样find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Multimedia) target_link_libraries(myapp PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets Qt6::Multimedia)这里我再强调一个跟工程配置相关、但是非常容易踩的运行时坑编译过了不等于能跑起来。不少人的程序在开发机上好好的拷贝到别的电脑上运行就报windows no qt platform plugin could be initialized在调用摄像头的程序里尤其常见。原因是发布时没有把 Qt 的 platform 插件platforms/qwindows.dll和 multimedia 相关的插件目录multimedia目录下的 ffmpeg、windowsmedia 等插件一起带上。我的建议是打包时直接用windeployqt生成依赖目录然后检查一下multimedia文件夹是否存在缺哪个补哪个不然换电脑就翻车。1.2 摄像头权限桌面端和移动端都得处理很多新手第一反应是代码写错了其实摄像头打不开很大概率是操作系统权限没给。Windows 10/11在设置 - 隐私和安全性 - 相机里需要允许桌面应用访问相机。如果你是用调试器跑的第一次弹的权限授权框没点允许后面调试就一直是拒绝状态得手动去设置里改。Linux当前用户必须在video组里否则无法访问/dev/video0。命令是sudo usermod -aG video $USER加完组要注销重新登录才生效。macOS需要在 Info.plist 里声明NSCameraUsageDescription否则程序一启动就会被系统强杀崩溃日志都看不到。Android要在 AndroidManifest.xml 里添加CAMERA和RECORD_AUDIO权限运行时还需要动态申请权限这个不能漏。我见过最典型的场景QCamera 对象创建成功了start()也调用了但error()信号一直报错state()永远停留在UnloadedState。查了半天下载记录最后发现是 Windows 隐私设置里把摄像头访问关掉了。所以一旦遇到这种诡异现象第一反应先查权限第二反应再查代码。2. 设备发现与选择别把第一个摄像头写死2.1 遍历摄像头列表现实中很多项目都是多个摄像头任选一个比如课堂录播、产线检测。直接把设备名写死是最不靠谱的做法因为 Windows 下同一个摄像头的设备名在不同机器上可能完全不一样而且同一个 UVC 摄像头从不同 USB 口插入枚举出来的描述也可能发生变化。推荐用QCameraInfoQt 5或者QMediaDevicesQt 5.14 和 Qt 6 都有遍历设备然后填到下拉框里// Qt 5 写法 const QListQCameraInfo cameras QCameraInfo::availableCameras(); for (const QCameraInfo info : cameras) { ui-comboCamera-addItem(info.description(), info.deviceName()); }注意我用了addItem(text, userData)这种带数据的写法界面上给用户看的是info.description()通常是USB2.0 Camera这种友好名称但真正传给 QCamera 构造函数的应该是info.deviceName()。很多新手直接把 description 传进去结果摄像头初始化失败还找不到原因。Qt 6 推荐用QMediaDevicesconst QListQVideoInputDevice inputs QMediaDevices::videoInputs(); for (const QVideoInputDevice device : inputs) { ui-comboCamera-addItem(device.description(), device.id()); }device.id()在 Windows 下是类似\\?\usb#vid_xxxxpid_xxxx的字符串这个才是内部唯一标识。别去解析这个 ID 的格式直接当不透明字符串用就行。2.2 监听热插拔USB 摄像头随时可能被拔掉、换口插如果程序不感知轻则画面卡死重则崩溃。Qt 提供了现成的信号connect(QMediaDevices::instance(), QMediaDevices::videoInputsChanged, this, MainWindow::refreshCameraList); // 连接到槽函数 void MainWindow::refreshCameraList() { const QString previousDevice ui-comboCamera-currentData().toString(); ui-comboCamera-clear(); const QListQVideoInputDevice inputs QMediaDevices::videoInputs(); for (const QVideoInputDevice device : inputs) { ui-comboCamera-addItem(device.description(), device.id()); } // 如果原来的设备还在就继续选中它 const int index ui-comboCamera-findData(previousDevice); if (index ! -1) { ui-comboCamera-setCurrentIndex(index); } }这里有个细节要记住设备拔掉后videoInputsChanged信号触发时旧的摄像机对象已经失效。在刷新列表之前必须先停掉正在使用的 QCamera 对象并释放再去枚举设备列表不然可能崩溃。设备重插回来之后摄像头所需的状态要全部重新初始化不要复用之前已经 stop 过的 QCamera 对象我建议直接 delete 后 new 一个新的省心很多。3. 实时预览QCameraViewfinder 与 QMediaCaptureSession3.1 Qt 5QCameraViewfinder 一行代码挂画面如果你是接手的老项目还在用 Qt 5画面显示的代码非常简单。先在 .ui 文件里拖一个QCameraViewfinder控件然后m_camera new QCamera(deviceId); m_camera-setViewfinder(ui-viewfinder); m_camera-start();三步就出画面。QCameraViewfinder本质上是一个 QVideoWidget 的派生控件可以直接嵌入到界面布局里甚至支持叠加绘图。但这套 API 有一个明显的局限逻辑全都绑死在控件上。如果你想同时把画面给到两个窗口或者想对帧数据做图像处理就得另想办法比如拿到 viewfinder 控件后通过 QPainter 去截图比较别扭。3.2 Qt 6QMediaCaptureSession QVideoWidgetQt 6 做了比较大的 API 重构推荐用法是把相机和输出对象分开通过QMediaCaptureSession来连接// 头文件成员 QCamera *m_camera nullptr; QMediaCaptureSession *m_captureSession nullptr; // 初始化 m_captureSession new QMediaCaptureSession(this); m_camera new QCamera(QMediaDevices::defaultVideoInput(), this); m_captureSession-setCamera(m_camera); m_captureSession-setVideoOutput(ui-videoWidget); // QVideoWidget m_camera-start();QMediaCaptureSession在这里扮演的是一个连接器角色左边接摄像头右边接显示控件、拍照器、录像器。这样设计的好处是解耦——画面显示归显示拍照归拍照录像归录像互不干扰。以后想加一个滤镜或者二次采集只需要在 session 上多挂一个QVideoSink就行代码结构清晰很多。我建议新项目直接用 Qt 6 的这套写法哪怕你暂时还在 Qt 5 上开发也可以用QMediaCaptureSessionQt 5.15 往后已经提供提前适配后面升级 amd64 或者用新版编译环境时少改一遍。3.3 预览对象的管理顺序这是个大坑值得单独说。QCamera 对象和显示控件之间一定不要搞错析构顺序先停止摄像头再销毁采集会话最后释放摄像头对象。反过来就会出现奇怪的崩溃或者下一个摄像头打开失败。反面教材是这样的// 错误示例直接 delete QCamera没有 stop delete m_camera; // 可能崩溃或者设备一直被占用正确做法m_camera-stop(); // 1. 停止采集 delete m_captureSession; // 2. 断开所有关联 delete m_camera; // 3. 释放相机对象这里面的原理是QCamera 持有底层视频采集设备句柄如果你不主动 stop设备和驱动之间没有正常握手关闭会导致两种后果一种是应用直接崩溃另一种是这个摄像头被占住了别的程序包括你下次启动的程序打开它就一直黑屏。4. 拍照与录像基础功能的完整实现4.1 拍照QCameraImageCapture / QImageCapture拍照有两种常用方式一种是直接保存到文件另一种是先拿到 QImage 做处理再保存。往往实际项目中两种都要比如拍完要立刻在界面上回显同时备份原图。Qt 5 的QCameraImageCapture可以同时满足这两个需求。它有三个信号imageCaptured在内存里拿到图像时触发imageSaved在文件写入完成后触发还有一个readyForCaptureChanged告诉你现在能不能拍照。m_imageCapture new QCameraImageCapture(m_camera); m_imageCapture-setCaptureDestination(QCameraImageCapture::CaptureToFile); connect(m_imageCapture, QCameraImageCapture::imageCaptured, this, [](int id, const QImage preview) { // 这里的 preview 是未经压缩的原始帧可以直接显示 ui-labelPreview-setPixmap(QPixmap::fromImage(preview)); }); connect(m_imageCapture, QCameraImageCapture::imageSaved, this, [](int id, const QString fileName) { qDebug() saved: fileName; });拍照的触发代码要注意加锁和解锁m_camera-searchAndLock(); m_imageCapture-capture(savePath); m_camera-unlock();searchAndLock是干什么的呢它会把摄像头暂时锁住让对焦和曝光稳定后再执行拍照避免快门按下的一瞬间取到的画面是糊的。如果拍摄场景光线稳定、摄像头是定焦的不锁问题也不大但在闸机、扫码这类对清晰度要求高的场景加上这一句明显能降低废片率。Qt 6 中对应的是QImageCapturem_imageCapture new QImageCapture(m_captureSession); m_captureSession-setImageCapture(m_imageCapture); connect(m_imageCapture, QImageCapture::imageCaptured, this, [](int id, const QImage preview) { ui-labelPreview-setPixmap(QPixmap::fromImage(preview)); }); m_imageCapture-captureToFile(savePath);接口名字略有不同但整体思路一致。4.2 录像QMediaRecorder录像是另一个高频需求比如做一个简易监控或者课堂录播。Qt 5 的写法是直接给 QCamera 挂一个 QMediaRecorderm_recorder new QMediaRecorder(m_camera); m_recorder-setOutputLocation(QUrl::fromLocalFile(QString(D:/rec/%1.mp4).arg(timestamp))); m_recorder-record();停止录像就调用m_recorder-stop()。Qt 6 里录音和录像统一走 sessionm_recorder new QMediaRecorder(m_captureSession); m_captureSession-setRecorder(m_recorder); // 如果想录出声音还需要配一个音频输入 m_audioInput new QAudioInput(m_captureSession); m_captureSession-setAudioInput(m_audioInput); m_recorder-setMediaFormat(QMediaFormat::MPEG4); m_recorder-setQuality(QMediaRecorder::HighQuality); m_recorder-setOutputLocation(QUrl::fromLocalFile(D:/rec/output.mp4)); m_recorder-record();这里有个容易被忽略的坑默认情况下 QMediaRecorder 只录视频不录声音。桌面端至少有麦克风的情况下你需要显式地把音频输入设置上去。如果摄像头自带麦克风很多 USB 摄像头有 mic要注意 QAudioInput 默认选中的是系统默认麦克风不一定是摄像头自带的那个如果发现录出来没声音大概率是音频输入设备选错了。再有就是录像文件的扩展名要和容器格式匹配。Qt 6 里设置了MPEG4容器但保存路径却写一个.avi录制会报错或者生成无法播放的文件。建议用.mp4和 MPEG4 容器配对兼容性最好。4.3 参数设置分辨率、帧率、对焦摄像头默认参数往往不适合你的场景。比如默认 640x48030fps你可能需要 1920x108025fps。通过QCameraViewfinderSettings设置QCameraViewfinderSettings settings; settings.setResolution(1920, 1080); settings.setMinimumFrameRate(15.0); settings.setMaximumFrameRate(30.0); if (m_camera-isViewfinderSettingsSupported(settings)) { m_camera-setViewfinderSettings(settings); } else { qWarning() 当前摄像头不支持该分辨率/帧率组合; }isViewfinderSettingsSupported这一步一定要做。有的廉价 USB 摄像头标称支持 1080p但实际输出的只有 30fps 的 MJPEG这时候如果直接设置不成文的分辨率摄像头会回退到最低配置甚至黑屏。更好的做法是先读取m_camera-supportedViewfinderSettings()看看这个设备到底支持哪些参数再从中选一个和目标最接近的。这个逻辑跟买鞋一样先看货架上有哪些尺码再挑最合脚的而不是硬塞。对焦方面QCameraFocus类提供了对焦模式设置QCameraFocus *focus m_camera-focus(); focus-setFocusMode(QCameraFocus::ContinuousFocus);连续对焦适合扫码、读证件这类需要随时变焦的场景固定焦点更适合闸机、人脸打卡这种人脸位置基本固定的场景反而能避免对焦来回拉风箱导致画面忽清晰忽模糊。5. 常见问题与排查技巧实录我在不同版本、不同平台的项目里调摄像头踩过的坑少说也有两位数这里整理成一份速查表按优先级排现象可能原因排查与解决办法摄像头对象创建成功但 start() 之后一直没画面系统权限未开启、设备被其他程序独占先查系统隐私权限关掉可能占用摄像头的软件Linux 查 video 组权限启动即崩溃报platform plugin错误发布目录缺少 Qt 插件用 windeployqt 重新部署确认 platforms 和 multimedia 目录被拷贝画面全黑但程序不报错分辨率设置不被支持、摄像头初始化立即取帧删除自定义分辨率设置等待 1~2 秒再操作热插拔 USB 摄像头后程序崩溃设备失效后未及时停止 QCamera监听videoInputsChanged先 stop 再 delete拍照保存的图片是黑的或花屏在摄像头未就绪时调用了 capture等state()变成ActiveState后再允许拍照录像文件无法播放容器格式与扩展名不匹配、缺少音频流统一用 MPEG4 .mp4按需设置音频输入Linux 下能枚举到设备但打开失败权限或设备节点被占用ls -l /dev/video*查看属主确认在 video 组检查是否有 ffmpeg 等进程占用5.1 摄像头打不开error() 报什么QCamera 有一个error(QCamera::Error)信号很多新手根本没连这个信号。建议一开始就把错误信号全部打出来connect(m_camera, QCamera::errorOccurred, this, [](QCamera::Error error) { qWarning() QCamera error: error m_camera-errorString(); });Qt 6 里统一为errorOccurred信号Qt 5 里老接口是error(QCamera::Error)新代码建议用errorOccurred以兼容较新版本。errorString()返回的描述有时候比较抽象但至少能帮你区分是设备被占用还是权限不足。如果显示的是Resource unavailable或者Device not found重点排查设备是否被其他程序占用比如浏览器、微信、Zoom 都可能霸占摄像头尤其是调试的时候最容易撞车。5.2 画面全黑黑屏问题我遇到得最多原因也五花八门。最常见的两个一是摄像头没有完全启动就尝试显示。QCamera 的start()是非阻塞的调用后底层驱动还在初始化马上设置 viewfinder 或者马上截图大概率拿到一帧黑图。我的经验是不要在start()后立刻操作画面而是通过stateChanged信号判断状态为ActiveState后再执行想做的事。或者简单粗暴一点start()之后加一个QTimer::singleShot(1000, ...)等待一秒再操作在实际项目里效果也很好。二是和分辨率设置冲突。有的摄像头在 UVC 协议下支持的格式列表很奇怪比如 1280x72030fps 只支持 YUYV不支持 MJPEG如果你用默认设置它可能给你一个不支持的组合结果就是黑屏。处理方法是先获取supportedViewfinderSettings()打印出所有支持的格式看清楚再设置。调试信息不要直接在 release 里打太多但开发期一定要留全。5.3 热插拔后崩溃这个问题在 Qt 5 里特别常见Qt 6 修复了一部分但也不能完全依赖。核心原因是USB 摄像头拔掉后底层设备文件消失但 QCamera 对象还持有旧设备句柄此时任何操作都会导致未定义行为。我的处理方案是在videoInputsChanged信号中不要只刷新下拉框还要主动切换状态void MainWindow::handleVideoInputsChanged() { m_camera-stop(); delete m_imageCapture; delete m_recorder; delete m_camera; m_camera nullptr; // 重新枚举设备列表 refreshCameraList(); // 重新选择当前设备并启动 startCurrentCamera(); }注意这里一定要彻底重建对象只做 stop() 然后复用旧对象是不够的因为底层驱动状态已经不干净了。重新 new 一个 QCamera 的成本极低却能把这类崩溃问题从根源上避免。5.4 运行时找不到平台插件文章开头提过no Qt platform plugin could be initialized这里展开说一下怎么排查。这个报错出现的原因通常是两个可执行文件目录下缺少platforms/qwindows.dllWindows 下platforms目录存在但插件版本和主程序版本不匹配比如程序是 Qt 5.15.2 编译的拷过去的插件却是 Qt 6.x 的。调用摄像头的程序还会多发一种情况缺少multimedia插件目录下的 dll。Qt 5 的 multimedia 插件包括mediaservice下的dsengine.dll、wmfengine.dllQt 6 则是 plugins 下的multimedia/ffmpegmediaplugin.dll、windowsmediaplugin.dll等。用windeployqt部署时一般是齐全的但如果你手动裁剪过 dll往往就漏在这。我的习惯是发布前在干净的虚拟机或普通电脑上跑一遍遇到缺 dll 就补比在开发机上自我感觉良好有用得多。5.5 有些摄像头枚举后出现重复项虚拟摄像头软件比如 OBS Virtual Camera、安卓模拟器的虚拟摄像头会出现在枚举列表里这本身不是 bug但会影响用户体验。处理办法是屏蔽名称中包含特定关键字的设备或者读取设备描述后做一次过滤。这个逻辑放在refreshCameraList之前执行就行。6. 进阶经验稳定采集的几条细节6.1 等待首帧的耐心摄像头从 start() 到输出第一帧画面中间经历枚举、驱动握手、格式协商、缓冲区初始化等过程实际耗时通常需要几百毫秒某些低端 USB 摄像头甚至要 2~3 秒。如果你在 start() 之后立刻轮询 QVideoSink 的帧信号大概率什么都拿不到。我的做法是维护一个m_ready标志位在拿到第一帧后再置位同时将按钮的 enabled 状态与它绑定。这样既能避免用户在初始化期间乱点拍照导致崩溃又让首帧等待过程对用户透明体验会比甩一个 加载中 要自然。6.2 设备释放顺序再啰嗦一遍释放顺序因为我在这个上面浪费过整整半天先停摄像头再断 session再删对象。如果你用的是栈对象或者智能指针务必要保证析构顺序比如在 MainWindow 的成员变量中m_captureSession和m_camera的声明顺序也很重要因为成员变量的析构顺序是声明顺序的逆序。我建议把m_camera声明在m_captureSession之前这样析构时会先析构 m_captureSession再析构 m_camera正好符合期望。// 头文件成员声明顺序 QCamera *m_camera nullptr; // 先声明 QMediaCaptureSession *m_captureSession nullptr; // 后声明如果反过来程序退出时可能偶尔崩一次而且只在特定机器上崩排查起来相当痛苦。6.3 从本地摄像头延伸到网络摄像头很多读者做到这一步接下来就会问能不能直接调海康、大华的网络摄像头或者把 OV5647树莓派摄像头、ESP32-S3 USB 摄像头也接入进来先说结论QCamera 只适合本地摄像头设备网络摄像头走的是 RTSP/ONVIF 协议需要另找方案。但如果是树莓派摄像头模块这类设备在 Linux 下通过 V4L2 驱动后QCamera 是可以直接枚举到的只是设备名可能是unicam或者platform前缀加一串数字需要在枚举列表里手动映射一个友好名称给用户。ESP32-S3 这类 USB 摄像头同理只要系统把它识别为标准 UVC 设备QCamera 这套 API 就能用。我个人的体会是QCamera 的价值在于它把 USB 摄像头、内置摄像头这类本地设备的接入门槛降到了很低的位置让开发者把精力集中在业务逻辑上。但它的坑也集中在设备状态、插件部署、权限这些基础层面所以每次在新电脑上部署项目时我都会按先查权限 - 再查插件 - 最后查代码的顺序排查这个流程帮我省下了大量时间。希望这份经验对你也有用。本文还有配套的精品资源点击获取