OpenCV 4.5.1编译wechat_qrcode模块的C++集成指南

二维码解码这事，听起来简单，真要在自己的 C++ 工程里落地，还是有不少坑。OpenCV 主仓库自带一套QRCodeDetector，常规场景能跑，可一旦二维码有倾斜、光照不均、拍摄距离远，识别率立刻断崖式下跌。后来微信团队开源的那套“检测 + 超分 + 解码”模型被收进了opencv_contrib的wechat_qrcode模块，实测下来对复杂场景的容错能力确实强一大截。这篇笔记就把 OpenCV 4.5.1 下编译wechat_qrcode并在 C++ 项目里使用的完整流程捋一遍，重点解决两件事：编译怎么一次过、调用怎么不翻车。适合准备在 Windows 下用 VS 编译 OpenCV、或者被二维码识别率折磨过的同学参考。

1. 先搞清楚选哪个：QRCodeDetector 还是 WeChatQRCode

1.1 两者定位差别

OpenCV 当前其实有两套可以处理二维码的模块。一套是主仓库opencv里的QRCodeDetector，在objdetect组件下，编译主仓库就能用，不需要额外扩展。它走的是传统图像处理路线：先用梯度、轮廓之类的方法把二维码区域捞出来，再做透视矫正，最后拿解码器解出内容。

另一套就是本文的主角wechat_qrcode，来自opencv_contrib扩展仓库。它默认不在主仓库里，必须要单独加模块编译。它的核心是微信团队贡献的检测模型和解码方案，检测部分用的是 CNN 网络，后面还接了一个超分模型，专门用来处理小尺寸、模糊、倾斜、局部遮挡的二维码。

我自己的使用体会是：如果只是识别干净的打印二维码，两者差别不大，QRCodeDetector甚至更快；但一旦把场景换成手机屏幕拍屏幕、卡片上的小码、或者隔着一定距离拍的码，QRCodeDetector的失败率会高得离谱，而WeChatQRCode基本还能稳住。所以选哪个，完全取决于你的业务场景对复杂二维码的容忍度。

1.2 WeChatQRCode 识别流程拆解

WeChatQRCode的识别流程粗看是“检测 -> 解码”，实际上内部做了三件事。

第一，通过一个 Caffe 模型检测二维码的位置。这个模型不是直接框出二维码的矩形，而是输出二维码的四个角点，所以对透视畸变有天然的适应性。你拿到的位置点就是四边形的四个顶点，后续绘制检测框直接连点就行。

第二，如果检测到的二维码区域面积太小，或者清晰度不够，会触发超分辨率模型sr，把这块区域先放大、修复边缘，再送去解码。这个设计很聪明，因为现实场景里小二维码占了绝大多数，直接用原始分辨率解经常解不出来。

第三，解码部分是基于轻量级库 quirc 改的。经过矫正和超分后的二维码图会先做二值化，再交给解码器。所以整体流程是“检测 CNN -> 透视矫正/裁剪 -> 超分增强 -> 二值化 -> 解码”，每一步都有针对性，鲁棒性自然比传统方案好。

1.3 为什么用 4.5.1 这个版本

OpenCV 版本更新很快，5.x 都出了，那为什么还要回过头用 4.5.1？不是因为它新，而是因为它“稳”。

wechat_qrcode模块在 4.5.x 时期接口已经很稳定，构造函数、detectAndDecode方法直到现在都没大改。同时这个时期 CMake 配置也相对简单，没有后来那些新增的依赖项和构建选项。如果你只是想在老项目里快速集成二维码能力，4.5.1 是个很省心的选择。

另外，4.5.1 的安装目录结构非常规律，Windows 下编译产物的 lib、dll 命名都很有辨识度，比如opencv_core451.lib、opencv_wechat_qrcode451.lib。在新的 4.10 或 5.x 里，命名和目录细节有调整，网上的教程又多半是不同版本混着写，新手很容易被绕晕。这篇笔记全部以 4.5.1 为准，你照着做不会对不上号。

2. 编译前准备：源码、工具链与模型文件

2.1 源码与版本匹配

编译 OpenCV 的 contrib 模块时，最忌讳的一件事就是主仓库和扩展仓库版本不匹配。你不能拿 OpenCV 4.5.1 的主仓库，配一个 master 分支的opencv_contrib，那样各种接口对不上，编译报错一定会让你怀疑人生。

正确做法是下载带版本标签的两个压缩包：

• OpenCV 主仓库opencv-4.5.1源码
• opencv_contrib-4.5.1源码

两个包解压到同一个父目录下，方便后面 CMake 配置时填写扩展模块路径。比如：

D:/work/opencv-4.5.1/ D:/work/opencv_contrib-4.5.1/

这样配置OPENCV_EXTRA_MODULES_PATH的时候指向D:/work/opencv_contrib-4.5.1/modules就行，一眼就能核对版本。

wechat_qrcode模块位于 contrib 仓库的modules/wechat_qrcode目录，打开后你会发现里面带了detect.prototxt、detect.caffemodel、sr.prototxt、sr.caffemodel四个模型文件。不过源码包里并不总是内置这些模型，后面单独讲怎么处理。

2.2 工具链下载与安装

Windows 上编译 OpenCV，我一般用 Visual Studio 2019 配合 CMake。VS2019 的社区版免费，C++ 桌面开发组件装一下就行。CMake 建议用 3.16 以上版本，能省掉不少兼容性麻烦。

有一点提前说明：wechat_qrcode的运行离不开opencv_dnn模块，因为模型是 Caffe 格式，DNN 模块负责加载推理。这也就意味着你编译的时候不能只编一个孤零零的wechat_qrcode，它依赖的core、imgproc、dnn等模块都要带出来。好在 CMake 配置好之后，构建系统会自动处理依赖，不用真的手动一个个勾选。

如果你只是临时用，也可以直接下载官方编译好的 OpenCV 二进制包，再单独编译opencv_contrib的wechat_qrcode源码，把生成的文件拼进去。但这种方式配置起来比整体编译还折腾，不如老老实实把 OpenCV 全量编一遍。我第一次偷懒试过拼库方案，最后因为 DNN 模块版本不一致反复崩溃，得不偿失。

2.3 模型文件准备

模型文件是整个识别功能的灵魂。wechat_qrcode在运行时要读取四个文件：

文件	用途
detect.prototxt	二维码检测网络的网络结构描述
detect.caffemodel	二维码检测网络的权重
sr.prototxt	超分网络的网络结构描述
sr.caffemodel	超分网络的权重

源码包里的wechat_qrcode模块目录不一定自带 caffemodel 权重（有些发行版会裁掉大文件），需要去 OpenCV 官方文档列出的模型地址下载。下载完以后，四个文件最好统一放在你自己工程的models目录里，路径不要带中文，也不要放在系统临时目录，因为每次启动程序都要读取，放太乱容易出奇葩问题。

sr那组模型是可选的。构造WeChatQRCode对象时如果不传超分模型，程序会把这一步跳过去，只在检测后直接解码。不过我会强烈建议你带上，因为小图、模糊图没有超分加持，成功率明显下降，这个模型文件也不大，没必要省。

3. CMake 配置与完整编译过程

3.1 CMake 参数逐项说明

在源码根目录下新建一个build文件夹，用来放构建产物。然后执行 CMake。这里给出一份我在 Windows 上稳定使用的配置命令，你可以直接复制修改。

cmake -S D:/work/opencv-4.5.1 -B D:/work/build ^ -G "Visual Studio 16 2019" -A x64 ^ -DCMAKE_BUILD_TYPE=Release ^ -DOPENCV_EXTRA_MODULES_PATH=D:/work/opencv_contrib-4.5.1/modules ^ -DBUILD_LIST=wechat_qrcode,dnn,core,imgproc,imgcodecs,videoio,highgui ^ -DBUILD_EXAMPLES=OFF ^ -DBUILD_TESTS=OFF ^ -DBUILD_PERF_TESTS=OFF ^ -DBUILD_opencv_python=OFF ^ -DBUILD_opencv_java=OFF ^ -DBUILD_opencv_world=OFF

逐项说下为什么这么配。

-G "Visual Studio 16 2019" -A x64指定生成 VS2019 的 x64 工程。32 位程序在二维码识别这种计算密集场景里优势不大，而且库的调用要额外注意指针宽度兼容，除非你有历史包袱，否则直接上 x64。

-DOPENCV_EXTRA_MODULES_PATH是开启 contrib 模块的入口，指向opencv_contrib的modules目录。配好这个，CMake 就会把 contrib 下的模块扫描进来。

-DBUILD_LIST是我比较喜欢用的精简参数。它指定了只构建哪些模块，避免把 OpenCV 全家桶都编一遍，能明显缩短编译时间。这里wechat_qrcode是目标，dnn是模型推理必需，core、imgproc、imgcodecs是图像处理和读取图片的底座，videoio、highgui是为后面摄像头实时识别和界面显示做准备。

注意，BUILD_LIST只是“显式列出”，构建系统会自动把wechat_qrcode依赖的其他模块也带上。比如它依赖的objdetect、features2d偶尔会被一起编出来，这是正常的，不用担心。

-DBUILD_EXAMPLES=OFF、-DBUILD_TESTS=OFF、-DBUILD_PERF_TESTS=OFF这几个关闭项能省非常多时间。OpenCV 官方自带的大量示例和测试用例编译起来非常耗时，但对最终使用毫无帮助。

-DBUILD_opencv_python=OFF和-DBUILD_opencv_java=OFF同理，如果你不需要 Python 或 Java 接口，果断关掉。尤其是 Python 接口，编译要额外装 Python 开发包，纯 C++ 项目完全没必要。

-DBUILD_opencv_world=OFF要不要关看个人习惯。如果打开，所有模块会被合成一个opencv_world451.lib，链接时只引一个库就行。关闭则是每个模块一个独立 lib。我习惯关掉，虽然要手动多配几个链接库，但出了问题定位方便，也更容易看清依赖关系。

配置完成后，CMake 会执行检测，如果一切正常，大概一两分钟后会在build目录里生成OpenCV.sln解决方案文件。

3.2 编译、安装与目录结构

CMake 结束之后，直接在命令行执行构建，比打开 VS IDE 点按钮更省事。

cmake --build D:/work/build --config Release --parallel 8

--parallel 8表示 8 线程并行编译，具体数字看你的 CPU 核心数，16 核机器开到 12~16 会更快。这一步是耗时大户，完整项目编下来在普通笔记本上可能要 30~60 分钟，如果只精简了模块，时间会短不少。

编译完成后，执行安装命令，让 OpenCV 把整理好的头文件、库文件、DLL 输出到统一的install目录。

cmake --install D:/work/build --config Release

安装完成后，你会得到这样一个目录结构：

D:/work/build/install/ ├── include/ │ ├── opencv2/ │ └── opencv4/ └── x64/ └── vc16/ ├── bin/ │ ├── opencv_core451.dll │ ├── opencv_dnn451.dll │ └── opencv_wechat_qrcode451.dll └── lib/ ├── opencv_core451.lib ├── opencv_dnn451.lib └── opencv_wechat_qrcode451.lib

注意 include 目录下有一个opencv4子目录。配 VS 工程时，附加包含目录要指向install/include/opencv4，否则会找不到opencv2/wechat_qrcode.hpp。这是 OpenCV 4.x 之后一个非常经典的坑，十个人有八个栽在这。

lib 目录下你会看到每个模块对应的.lib文件。release 模式的库名不带d后缀，debug 模式会多一个d，比如opencv_core451d.lib。平时只做 Release 就认准不带 d 的版本。

3.3 集成到自己的 C++ 工程

编译好的 OpenCV 要接入自己的工程，总共三步。

第一步，VS 的“C/C++ -> 常规 -> 附加包含目录”添加：

D:/work/build/install/include/opencv4

第二步，“链接器 -> 常规 -> 附加库目录”添加：

D:/work/build/install/x64/vc16/lib

第三步，“链接器 -> 输入 -> 附加依赖项”按需添加下面这些库：

opencv_core451.lib opencv_dnn451.lib opencv_imgproc451.lib opencv_imgcodecs451.lib opencv_highgui451.lib opencv_videoio451.lib opencv_wechat_qrcode451.lib

少了一个库，链接时会报类似“无法解析的外部符号”的错误。我一般先把所有用到模块的 lib 全加上，跑通了再按需删减，省得反复编译来回试。

运行时别忘了把install/x64/vc16/bin下的 DLL 复制到 exe 同目录，或者加到系统 PATH。这个问题经常导致“程序能编过但双击闪退”的诡异现象，实际就是缺 DLL。

4. C++ 实战：单图识别、坐标获取与实时摄像头

4.1 最简单图识别 Demo

准备工作做完，直接上代码。下面这段是最基础的 C++ 单图识别程序，完整展示了WeChatQRCode的构造和调用。

#include <opencv2/opencv.hpp> #include <opencv2/wechat_qrcode.hpp> #include <iostream> int main() { // 模型文件路径，按你的实际目录修改 std::string detector_proto = "models/detect.prototxt"; std::string detector_model = "models/detect.caffemodel"; std::string sr_proto = "models/sr.prototxt"; std::string sr_model = "models/sr.caffemodel"; cv::Ptr<cv::wechat_qrcode::WeChatQRCode> qrcode; try { qrcode = cv::makePtr<cv::wechat_qrcode::WeChatQRCode>( detector_proto, detector_model, sr_proto, sr_model); } catch (const cv::Exception& e) { std::cerr << "模型加载失败: " << e.what() << std::endl; return -1; } cv::Mat img = cv::imread("test.png", cv::IMREAD_COLOR); if (img.empty()) { std::cerr << "图片读取失败" << std::endl; return -1; } std::vector<cv::Mat> points; std::vector<std::string> results = qrcode->detectAndDecode(img, points); if (results.empty()) { std::cout << "未识别到二维码" << std::endl; } for (size_t i = 0; i < results.size(); ++i) { std::cout << "二维码内容: " << results[i] << std::endl; } return 0; }

detectAndDecode返回的是一个std::vector<std::string>，因为一张图里可能同时有多个二维码，每个结果对应一个识别内容。如果结果为空，说明这张图里没找到可解码的二维码。

构造函数中，如果不传sr_proto和sr_model，也可以正常构造，但识别小码的成功率会下降。我实际测试下来，同一个模糊样本，带超分和不带超分，成功率差距大概在 20% 到 40%，所以强烈建议把四个模型都配齐。

模型加载失败时，WeChatQRCode的构造函数会抛异常，所以外面套了一层 try-catch。异常信息里如果出现fs.is_open()、cannot open file这类关键词，大概率就是路径配错了。

4.2 获取二维码位置与矫正结果

detectAndDecode的第二个参数能拿到每个二维码的轮廓点。这些点本质上是一个Mat，尺寸是 4 行 2 列，依次是左上、右上、右下、左下四个顶点坐标。拿到它们就可以画框，比如把识别到的二维码区域用线框标出来。

for (size_t i = 0; i < results.size(); ++i) { if (!points[i].empty()) { std::vector<cv::Point2f> corners; for (int r = 0; r < points[i].rows; ++r) { float x = points[i].at<float>(r, 0); float y = points[i].at<float>(r, 1); corners.push_back(cv::Point2f(x, y)); } // 连成四边形框 std::vector<cv::Point2f> poly; poly.push_back(corners[0]); poly.push_back(corners[1]); poly.push_back(corners[2]); poly.push_back(corners[3]); cv::polylines(img, poly, true, cv::Scalar(0, 255, 0), 3); } }

画完框之后可以直接cv::imwrite("result.png", img)保存检测结果图。这步调试非常有用，我经常把检测不到或者识别错误的图单独存下来，肉眼排查到底是位置检测失败还是解码失败。

另外，WeChatQRCode的第二个参数里返回的是原图中的四边形顶点，不是裁剪后的二维码图。如果需要把矫正后的二维码图单独拿出来研究，可以自己根据四个顶点做透视变换，也就是cv::getPerspectiveTransform加cv::warpPerspective。有些场景下你会发现，解码失败但检测成功了，这时候手动把矫正图导出，用其他库二次解析，也是一个后备方案。

4.3 摄像头实时识别

单图识别跑通了，摄像头实时识别只需要把图源从imread换成VideoCapture。下面是一段可以直接跑的实时循环示例。

#include <opencv2/opencv.hpp> #include <opencv2/wechat_qrcode.hpp> #include <iostream> int main() { cv::Ptr<cv::wechat_qrcode::WeChatQRCode> qrcode = cv::makePtr<cv::wechat_qrcode::WeChatQRCode>( "models/detect.prototxt", "models/detect.caffemodel", "models/sr.prototxt", "models/sr.caffemodel"); cv::VideoCapture cap(0); if (!cap.isOpened()) { std::cerr << "打开摄像头失败" << std::endl; return -1; } cap.set(cv::CAP_PROP_FRAME_WIDTH, 1280); cap.set(cv::CAP_PROP_FRAME_HEIGHT, 720); cv::Mat frame; while (cap.read(frame)) { std::vector<cv::Mat> points; std::vector<std::string> results = qrcode->detectAndDecode(frame, points); for (size_t i = 0; i < results.size(); ++i) { std::cout << "识别结果: " << results[i] << std::endl; // 这里可以在结果里去重，避免同一帧重复打印 } cv::imshow("QRCode", frame); if (cv::waitKey(1) == 27) break; // ESC 退出 } return 0; }

实时场景里需要注意两点。第一，detectAndDecode用的是 CNN 模型，720p 图像在普通桌面 CPU 上单次推理大概要 60 到 150 毫秒，帧率不会像人脸识别那样快。如果觉得卡，可以把输入帧缩小到 960 宽度左右再识别，代价是远距离小码的成功率下降。第二，摄像头连续识别同一个二维码会重复输出结果，业务里通常要加一个“结果去重 + 冷却时间”的逻辑，比如同一内容在 2 秒内不重复上报。

如果你想提升准确率，可以把cap.set的曝光参数固定住，防止摄像头自动曝光导致画面忽明忽暗。具体参数不同摄像头差别较大，可以在程序里用cv::CAP_PROP_EXPOSURE实验。

4.4 提高识别率的预处理手段

模型再强，输入质量太差也一样白搭。以下这几个预处理手段是我在项目里实测过有效的方法。

第一是缩放补偿。如果你发现二维码在画面里太小，先用cv::resize把整帧放大 1.5 到 2 倍再识别，比直接把小图交给模型要稳得多。超分模型虽然能处理小图，但它的能力也有上限，不如从源头提高分辨率。

第二是光照处理。二维码识别对光照挺敏感，过暗、过曝都会让二值化失效。简单做法是转灰度后做一次 CLAHE 自适应直方图均衡化，能把局部对比度拉起来，减少暗角和反光的影响。这个操作成本很低，值得加进预处理流程。

cv::Mat gray, enhanced; cv::cvtColor(frame, gray, cv::COLOR_BGR2GRAY); cv::Ptr<cv::CLAHE> clahe = cv::createCLAHE(3.0, cv::Size(8, 8)); clahe->apply(gray, enhanced);

第三是多媒体编码带来的图像伪影。从视频流里取出来的帧如果经过了高压缩比编码，二维码边缘会产生马赛克和振铃效应。这种情况下，可以尝试把VideoCapture的分辨率设低一点，或者改用摄像头输出的原始流，让编解码器少介入。

另外，不要把太多预处理逻辑堆在识别前。wechat_qrcode自己已经做了灰度化、二值化、矫正，再叠加一堆滤镜反而容易破坏角点结构。我见过一个同事用高斯模糊去噪，结果二维码边缘糊成一团，识别率反而掉了。预处理要克制，能不上就不上。

5. 常见问题与排查技巧

5.1 编译类问题速查

编译是整个流程里最容易劝退新手的环节。我把常见错误整理成了一张表，每个都是我自己或身边同事踩过坑后总结出来的。

现象	可能原因	解决办法
CMake 里找不到 wechat_qrcode 模块	OPENCV_EXTRA_MODULES_PATH指错位置	检查是否指向opencv_contrib-4.5.1/modules而不是opencv_contrib-4.5.1
编译报错：接口不一致	主仓库与 contrib 版本不匹配	统一换成 4.5.1 源码包
找不到opencv2/wechat_qrcode.hpp	VS 附加包含目录少了一层	把 include 目录改为install/include/opencv4
链接时一堆无法解析的外部符号	附加依赖项漏了模块库	按依赖列表补全.lib
编译时间长到想放弃	没开BUILD_LIST	重新配置 CMake，只编需要的模块
Debug 和 Release 库混用	链接了带d和 不带d的库	统一模式，不要混用

加一个我特别想强调的点：不要在装有杀毒软件的机器上反复编译 OpenCV，尤其是实时文件监控型杀软，会在编译过程中锁住临时文件，产生各种随机性的 “Permission denied” 或 “LNK1104 无法打开文件”。如果碰上了，把build目录加入杀软白名单，或者直接关掉监控再编译，问题立刻消失。

5.2 运行类问题速查

程序能编过，不代表能跑通。运行时的问题比编译期更隐蔽，因为多半是模型文件、DLL、路径这些环境因素。

现象	可能原因	解决办法
启动就崩溃/闪退	缺少 DLL	把install/x64/vc16/bin下 DLL 复制到 exe 目录
抛异常：fs.is_open()	模型文件路径错误	检查四个模型是否都存在、路径是否可读
抛异常：网络结构不匹配	prototxt 与 caffemodel 不是同一套模型	四件套必须配套下载，不要混用
识别永远为空	二维码本身损坏，或模型加载被跳过	先跑官方测试图，排除模型问题
中文内容乱码	控制台编码问题	程序里设置setlocale(LC_ALL, "")或改用 UTF-8 输出

如果模型加载成功但识别结果一直是空的，最快的排查办法是换一张 OpenCV 官方文档里的标准测试二维码。如果标准码也识别不出来，说明模型加载有问题或者 DNN 模块被裁剪了，优先检查编译时BUILD_LIST是否真的包含了dnn。

关于中文乱码，这里多说一句。wechat_qrcode返回的字符串是二维码里的原始文本，如果内容是 GBK 编码的 URL 或中文，Windows 控制台默认编码不一致就会显示乱码。这属于显示问题，不是识别错误。你可以先把result字符串输出到文件里，用十六进制查看器看内容是否正确，或者统一转成 UTF-8 再打印。

5.3 识别效果问题

识别成功率的优化，很多时候不是改代码，而是改场景。下面几个方向是我在实际项目里逐个验证过的。

距离和尺寸直接决定成败。同样一个二维码，距离近一点、占画面 1/4 左右，识别率最高。太远时模块会尽力超分，但超过极限后照样失败。落地到业务上，最好在界面上做一个“请将二维码对准框内”的提示，从交互层面减少识别压力。

反光和塑料膜是二维码的两大杀手。反光会让二维码变成一片白，塑料膜会让图像模糊并产生条纹。这种场景能做的有限：一是调整摄像头角度，尽量避免光源直射；二是在多次识别失败时提示用户“擦拭/调整角度”。算法层面能做的只是多加一两次 CLAHE，效果有限。

还有一点很容易被忽略：二维码版本越高，图像越密，同样尺寸下解码难度越大。V1 版本（21x21 模块）和 V10 版本（57x57 模块）的体积差距非常大。如果你的业务能控制二维码内容长度，尽量让二维码模块数少一点、留白多一点，识别率会明显上升。

6. 实测对比与几点心得

6.1 WeChatQRCode 与 QRCodeDetector 实测对比

我在一台 i5-8400、8GB 内存、Release x64 的机器上，用同一批测试样本做了对比。样本包括打印纸二维码、手机屏幕二维码、卡片上的小尺寸二维码、以及带轻微透视畸变的二维码。

测试场景	QRCodeDetector 成功率	WeChatQRCode 成功率	720p 单帧耗时
标准打印二维码	约 98%	约 99%	5~15ms vs 60~100ms
手机屏幕拍照	约 60%	约 95%	5~15ms vs 80~120ms
小尺寸卡片二维码	约 30%	约 85%	5~15ms vs 70~110ms
轻微透视畸变	约 40%	约 90%	5~15ms vs 70~120ms

需要强调的是，QRCodeDetector的“快”是在它成功识别的前提下，一旦识别失败，再快也没意义。现实项目里如果因为识别不出二维码而导致用户体验断裂，这多出来的几十毫秒完全可以接受。所以我的结论很清楚：只要你的场景不是二维码识别率百分之百的理想环境，直接上WeChatQRCode。

不过，WeChatQRCode也不是万能的。极端情况下，比如二维码被大面积遮挡、强烈的镜面反光、或者严重模糊，它一样会失败。这时候别硬扛，换一个思路：把连续多帧的检测结果做投票融合，或者同时把画面保存下来转入人工处理，比在算法里死磕更务实。

6.2 个人经验总结

从第一次编译 OpenCV 到现在，微信二维码识别这功能我前前后后折腾过好几轮。说几个只有踩过坑才能体会的经验。

模型文件一定要当宝贝一样固定放好。不要在每次启动时动态下载，也不要放在临时目录。我就吃过亏，程序部署到客户机器上，模型路径写的是相对路径，结果客户从不同目录启动导致模型加载失败，排查了整整半天。后来统一改成绝对路径 + 启动时检查文件存在，再没出过这种问题。

编译参数尽量一次定好，别反复改。OpenCV 的增量编译虽然支持，但改了 CMake 选项之后经常要重新生成解决方案，如果遇到诡异的报错，最保险的做法是build目录整个删掉，重新配置重编。这个听起来很暴力，但实际是最省时间的。

如果你在 Linux 服务器上部署，千万别忘了把模型文件路径从 Windows 风格改成 Linux 风格，并且注意文件权限。跨平台项目里，路径分隔符和文件编码是两座绕不开的大山。

最后再分享一个小技巧：如果项目对体积敏感，不愿意为了二维码功能编译整个 OpenCV，可以考虑只编译wechat_qrcode及其依赖模块，最后把install/x64/vc16/bin中的 DLL 精简到目标依赖的十几个文件。实测下来，最小可用集大约 30 到 40MB 左右，对于现代应用完全可接受。

微信二维码识别这个功能，确实是把 OpenCV 从“实验室玩具”变成“生产工具”的典型代表。希望这篇笔记能帮你少走一遍我走过的弯路。