简介：面向在Linux平台使用Qt C++接入海康威视SDK的开发者，重点解决实时视频流获取与云台控制这两类工程问题，适合具备C++、Qt网络编程和SDK调用基础的中级读者参考。压缩包共36个文件，约10.34MB，包含23个so动态库、4个头文件、2个cpp源文件及ui界面、CMake配置和日志XML等，动态库与头文件对应海康SDK运行依赖，源码与界面文件便于对照理解取流、预览和PTZ命令的调用关系。已有2768人学习，说明该主题在安防监控与视频客户端开发中关注度较高。包内提供可编译的Qt工程骨架，覆盖设备连接、通道打开、视频解码显示、云台方向与变倍控制，以及多线程取流、异常处理和Linux动态库部署等关键环节，可作为搭建监控客户端原型、排查SDK链接与播放问题的实践参考。
1. 一条 RTSP 能跑通，不代表 SDK 取流能落地：Linux Qt 接安防相机 SDK 的真实边界
不少团队先用播放器拉一路 RTSP，觉得视频流不过如此；真正换到 Linux 下的 Qt C++ 工程里，接安防相机 SDK 做实时取流和云台控制，问题才刚开始：回调线程不是 UI 线程、YUV 帧要自己管生命周期、云台指令还要和码流状态对齐。这个资源对应的是一套可落地的工程骨架：Linux 上编译 Qt C++ 程序，加载厂商 SDK 动态库，登录相机、按通道取主/子码流，再把云台连续移动、预置点、变倍聚焦接进业务界面。适合正在做安防预览客户端、机器人上位机、边缘盒子的开发者；不适合只想拉一路 RTSP 看看画面的场景。下面按工程骨架、取流渲染、云台控制、排查顺序拆开。
2. 工程骨架：把厂商 SDK 塞进 Qt C++ 的四个边界
Linux 下接 SDK 不是加个头文件就完事。Qt 工程常见 qmake 和 CMake 两套，我更倾向 CMake，因为厂商 SDK 往往依赖一堆 .so，CMake 的 target 级链接和 rpath 更好控。先定取流路径，再谈界面。很多人一上来问“SDK 取流和 RTSP 哪个好”，这个问题要落到业务：需要设备端智能帧、告警、原始码流、低延迟云台联动，选 SDK 回调；只需要看画面、跨厂商兼容，选 RTSP/ONVIF；两者都要，做混合，但不要让两条链路抢同一个解码器。
2.1 先定取流路径：SDK 回调、RTSP 拉流还是混合
SDK 回调的优势是拿得到设备侧更细的数据类型，比如原始码流、YUV、音频、私有帧头，云台控制也通常和登录句柄绑定，少一层协议适配。代价是厂商库只支持特定架构，现场依赖 .so，升级 SDK 要重新回归。RTSP 拉流的优势是跨厂商、调试工具多，用常见播放器就能对照；代价是拿不到设备私有信息，云台要走 ONVIF 或其他通道，延迟和丢包策略也更依赖网络。混合方案常见于“预览走 RTSP，云台走 SDK”或“主码流走 SDK，子码流走 RTSP”，前提是两条链路的帧时间戳能对齐，否则 UI 上会出现画面和云台状态不同步。
| 取流路径 | 适合场景 | 主要成本 | 常见翻车点 |
|---|---|---|---|
| SDK 回调 | 需要私有帧、告警、低延迟云台联动 | 依赖厂商 .so，架构受限 | 回调线程直接碰 UI，帧缓冲复用导致花屏 |
| RTSP 拉流 | 跨厂商预览、快速验证 | 云台要另走协议 | UDP 丢包、TCP 延迟累积 |
| 混合 | 预览和云台分别选型 | 时间戳与状态同步 | 两条链路重复登录、句柄泄漏 |
我一般会先把 SDK 回调路径跑通，再用 RTSP 做对照。如果 SDK 回调能出帧而 RTSP 也正常，问题多半在渲染；如果两边都黑，先查网络、通道号和码流类型。这个顺序能少走很多弯路。
2.2 CMake 链接 .so 与头文件：把运行路径写死比 LD_LIBRARY_PATH 稳
厂商 SDK 解压后通常是include/、lib/、bin/三块，头文件放 include，动态库放 lib，运行时依赖放 bin。工程里不要用全局link_directories，用 target 级包含和链接，避免污染其他 target。下面这份 CMakeLists 是虚构工程camera_qt的骨架，vendor_sdk代指厂商 SDK 目录，实际按手里的包替换。
cmake_minimum_required(VERSION 3.16) project(camera_qt LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) find_package(Qt5 REQUIRED COMPONENTS Widgets OpenGL) find_package(Threads REQUIRED) # 厂商 SDK 目录约定：include/ 放头文件，lib/ 放 .so，bin/ 放运行时依赖 set(VENDOR_SDK_ROOT "${CMAKE_SOURCE_DIR}/third_party/vendor_sdk") add_executable(camera_qt src/main.cpp src/mainwindow.cpp src/sdk_bridge.cpp src/video_widget.cpp ) target_include_directories(camera_qt PRIVATE "${VENDOR_SDK_ROOT}/include" "${CMAKE_SOURCE_DIR}/src" ) target_link_libraries(camera_qt PRIVATE Qt5::Widgets Qt5::OpenGL Threads::Threads "${VENDOR_SDK_ROOT}/lib/libvendor_sdk.so" ) # 把运行时搜索路径写进可执行文件，减少“开发机能跑、现场机找不到 .so”的翻车 set_target_properties(camera_qt PROPERTIES BUILD_RPATH "${VENDOR_SDK_ROOT}/lib;${VENDOR_SDK_ROOT}/bin" INSTALL_RPATH "$ORIGIN/../lib;$ORIGIN/../bin" )这段的关键在BUILD_RPATH和INSTALL_RPATH。BUILD_RPATH解决开发阶段找库，INSTALL_RPATH用$ORIGIN让安装目录可搬家，现场把可执行文件和 lib、bin 一起打包即可。target_link_libraries里直接写绝对路径在开发机没问题，但打包时要改成导入 target 或安装规则，否则换一台机器路径就断。Threads::Threads不是摆设，SDK 回调和 UI 线程之间要用条件变量、原子量，后面帧队列会用到。
提示：不要只靠
LD_LIBRARY_PATH。终端里能跑，换成桌面自启动或服务方式启动时环境变量经常丢，最后表现就是“昨天还好好的，今天找不到 .so”。
2.3 初始化、登录、预览句柄的生命周期
SDK 的初始化、登录、预览是三层句柄：全局初始化一次，登录返回用户句柄，预览返回预览句柄。常见错误是把预览句柄放在局部变量里，函数返回后没人 stop，下一次再开就资源泄漏。下面用Vendor_前缀代指厂商接口，实际替换成 SDK 头文件里的函数名和参数结构。
// sdk_bridge.h #pragma once #include <atomic> #include <cstdint> #include <string> struct LoginResult { long userId = -1; int sdkError = 0; }; class SdkBridge { public: bool init(); LoginResult login(const std::string& ip, int port, const std::string& user, const std::string& pwd); long startPreview(long userId, int channel, int streamType); void stopPreview(long previewHandle); void logout(long userId); void cleanup(); private: std::atomic<bool> inited_{false}; };// sdk_bridge.cpp #include "sdk_bridge.h" #include "vendor_sdk.h" // 厂商头文件，实际函数名按 SDK 文档替换 bool SdkBridge::init() { if (inited_.load()) return true; if (!Vendor_Init()) { int code = Vendor_GetLastError(); // 常见：依赖库缺失、授权文件路径不对、重复初始化 return false; } inited_.store(true); return true; } LoginResult SdkBridge::login(const std::string& ip, int port, const std::string& user, const std::string& pwd) { Vendor_LoginParam p{}; p.ip = ip.c_str(); p.port = port; // 设备服务端口，常见 8000/80/554，以现场为准 p.user = user.c_str(); p.pwd = pwd.c_str(); p.timeoutMs = 3000; // 不要用默认无限等，否则 UI 线程会被拖死 long userId = Vendor_Login(&p); if (userId < 0) { return { -1, Vendor_GetLastError() }; } return { userId, 0 }; } long SdkBridge::startPreview(long userId, int channel, int streamType) { if (userId < 0) return -1; Vendor_PreviewParam p{}; p.userId = userId; p.channel = channel; // 通道号从 1 开始还是 0 开始，必须看设备文档 p.streamType = streamType; // 0 主码流，1 子码流，实际枚举按 SDK 头文件 p.callback = &SdkBridge::onStream; // 回调必须是静态函数或全局函数 p.user = this; // 把 this 透传回回调，用于投递帧 return Vendor_StartRealPlay(&p); }login里的timeoutMs
本文还有配套的精品资源，点击获取