opencv 4.7+ 原生支持 qrcodedetector，无需额外库；4.5 及更早版本会编译失败或返回空字符串，需检查版本并捕获 cv::exception。
OpenCV 4.7+ 自带 QRCodeDetector，无需额外库
OpenCV 从 4.7 版本起原生支持二维码检测与解码，不需要再集成 zbar 或 libqrencode。如果你用的是 4.5 或更早版本，QRCodeDetector 会编译失败或返回空字符串——这是最常见的“识别失败”原因。
确认版本的方法很简单：
std::cout 输出类似 <code>4.8.1</code> 才能放心用下面的流程。
- 确保链接了
opencv_objdetect模块（CMake 中要加find_package(OpenCV REQUIRED COMPONENTS core imgproc objdetect)） - 输入图像建议转成灰度图：
cvtColor(img, gray, COLOR_BGR2GRAY)，彩色图也能跑但稳定性下降 -
QRCodeDetector::detectAndDecode()是单次调用完成检测+解码的最简接口，别先调detect()再手动传角点——容易因坐标格式不匹配导致崩溃
detectAndDecode() 返回空字符串的典型原因
函数返回空串，不代表没二维码，而是解码失败。常见触发条件有：
- 图像过小：二维码边长低于 30 像素时，定位角点易丢失；建议上采样：
resize(img, img, Size(), 2.0, 2.0, INTER_CUBIC) - 光照不均或反光：局部过曝/阴影会破坏三个定位角的对比度；可用
CLAHE增强：Ptr<clahe> clahe = createCLAHE(2.0, Size(8, 8));<br>clahe->apply(gray, gray);</clahe>
- 二维码被遮挡或扭曲严重：该函数不支持透视校正后的重解码，只处理原始平面图像
- 二维码格式非标准：如自定义掩膜、非 ISO/IEC 18004 规范的变体（某些企业私有码），
QRCodeDetector会静默失败
批量识别多张图时如何避免内存泄漏
每次调用 QRCodeDetector::create() 都会分配内部状态对象，循环中反复创建会导致显著开销甚至泄漏。正确做法是复用同一个 detector 实例：
Ptr<qrcodedetector> detector = QRCodeDetector::create();<br>for (const auto& path : image_paths) {<br> Mat img = imread(path);<br> if (img.empty()) continue;<br> string decoded;<br> try {<br> decoded = detector->detectAndDecode(img);<br> } catch (...) {<br> // OpenCV 有时抛 cv::Exception 而非返回空，需捕获<br> }<br> if (!decoded.empty()) {<br> cout }<br>}</qrcodedetector>
- 不要在循环内写
QRCodeDetector::create() - 对可能损坏的图片（如 JPEG 解析失败）加
img.empty()判断，否则detectAndDecode可能 SIGSEGV - 部分 OpenCV 构建版本（尤其 Android NDK）禁用了异常，此时应依赖返回值判断，而非 try/catch
识别结果坐标系和 OpenCV 坐标惯例一致
detectAndDecode() 只返回字符串，但如果你需要定位框，得拆成两步：detect() 得到四点坐标，再喂给 decode()：
vector<point> points;<br>string decoded = detector->detectAndDecode(img, points);<br>// points 是顺时针四个角，对应左上→右上→右下→左下<br>// 可直接用 polylines() 绘制：<br>polylines(img, points, true, Scalar(0,255,0), 2);</point>
- 返回的
points是vector<point></point>，不是Mat或数组，别误用points.at(0).x以外的索引方式 - 如果
decoded为空但points非空，说明检测到了图案但无法解码——这时候可以裁剪该区域后尝试其他解码器（如pyzbar的 C++ binding） - 注意 OpenCV 默认坐标原点在左上角，
Point的x是列，y是行，跟数学习惯相反
真正卡住人的往往不是算法，而是灰度预处理强度、detector 复用时机、还有那个总被忽略的 OpenCV 版本检查。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
