简介ZXing 是知名的开源条码/二维码解码库最初以 Java 实现本资源是其 C 移植版本的分叉面向需要在 OpenCV、Qt、Visual Studio 等环境中集成条码识别能力的 C 开发者。该资源提供经整理的源码与 CMake 构建配置可避开上游仓库中已移除的 Python 构建系统和测试数据的干扰直接用于二次开发或学习条码解码实现。资源包共 260 个文件压缩后仅 493KB以 h/cpp 头文件与源码文件为主119 个 h、113 个 cpp辅以 CMake 构建脚本、Makefile、说明文档、许可与作者信息等结构集中便于快速定位核心实现和编译入口已有 1054 人浏览学习。从内容预览来看包内包含 BigInteger、BigUnsigned 等多精度运算源码、win_iconv 编码转换实现、FindIconv 与源文件收集等 CMake 辅助脚本说明该库对底层数据运算与跨平台编码处理做了完整封装。读者可借此掌握 ZXing 在 C 环境下的工程组织方式并直接引入自己的 OpenCV 项目用于二维码/条码识别。1. zxing-cppC 项目里识别二维码为什么绕不开这个库做过扫码枪接入、设备巡检、自动称重这类 C 端落地的人都懂Java 生态里有 ZXingC 里真正能打的条码库反而不多。zxing-cpp 就是把经典 ZXing 算法用 C 重写的那份社区实现核心库只管识别和生成不绑架你的图像 IO、不强制绑定某个界面框架。它能读 QR Code、Data Matrix、Aztec也能读 Code 128、EAN-13 等常见一维码生成二维码同样走一套 C API。最实用的场景是把扫码能力嵌进一个已有 CMake 工程里几行就能调用。这篇文章会从编译开始讲到解码参数、生成二维码再列出我实际踩过的几类坑最后给出一套现场调参的顺序。对新手来说照着走能跑通对熟手来说你可以直接跳到避坑那章对症状。2. 编译与接入 zxing-cpp三种集成方式和一次冒烟验证2.1 从源码编译 Release 库CMake 开关怎么给zxing-cpp 源码本身是标准的 CMake 工程核心库不依赖图像解码库所以你编译时不需要先装libpng这类东西。常见的做法是独立建一个 build 目录编译完把库安装到固定前缀下。以命令行方式为例git clone zxing-cpp 官方仓库地址 cd zxing-cpp cmake -S . -B build -DCMAKE_BUILD_TYPERelease \ -DBUILD_EXAMPLESOFF \ -DBUILD_BLACKBOX_TESTSOFF \ -DBUILD_UNIT_TESTSOFF cmake --build build -j4 cmake --install build-DCMAKE_BUILD_TYPERelease一定要开。条码识别这类计算密集代码Debug 和 Release 的速度差距经常超过一倍。BUILD_BLACKBOX_TESTS和BUILD_UNIT_TESTS关掉能少编译不少东西省时间。默认编出来是静态库想要.so可以再追加-DBUILD_SHARED_LIBSON。编译完成后重点不是看输出而是确认你拿到了三样东西头文件目录、静态库文件、以及 CMake package。执行cmake --install后头文件默认放在include/zxing/库文件是libZXing.a或libZXing.soCMake package 文件在lib/cmake/ZXing/。后面接进项目主要靠这套安装目录。版本之间 CMake 选项名有出入最稳妥的检查命令是cmake -LA build | grep -E BUILD|ZXING|CMAKE_BUILD不同 tag 下面也许冒出来一个ZXING_READERS或者ZXING_WRITERS先看这份开关列表再决定要不要动。我一般会保持EXAMPLESOFF但第一次在一个陌生环境编译时会把EXAMPLESON打开一次因为后面冒烟验证很快。2.2 接进自己的 CMake 工程add_subdirectory 和 find_package 怎么选接入方式基本两种一种是把 zxing-cpp 源码直接放进third_party用add_subdirectory编进来另一种是先安装到系统目录或指定前缀主工程用find_package找。add_subdirectory的写法# 假设 zxing-cpp 源码已经放在 third_party/zxing-cpp add_subdirectory(third_party/zxing-cpp) target_link_libraries(my_app PRIVATE ZXing::ZXing)find_package的写法find_package(ZXing REQUIRED) target_link_libraries(my_app PRIVATE ZXing::ZXing)add_subdirectory的好处是版本跟着主工程走调试时能直接跳进 zxing-cpp 源码里看中间结果坏处是每次全量编译都要带着它编一遍即使你一行没改。find_package则要求先执行过cmake --install主工程干净换库版本只需换安装前缀。如果你用包管理器那就更省事了包管理器里搜到zxing-cpp就能直接装。但要注意包管理器里的库可能和你代码版本不一致解码能力有差异项目上线前最好用黑盒图集测一遍。链接时有个最隐蔽的问题CMake target 名字在不同版本里不完全一致。老版本可能叫zxing而不是ZXing::ZXing。碰到链接报错先看 build 系统里真实目标名cmake --build build --target help | grep -i zxing看到ZXing还是zxing照抄进target_link_libraries就不会错。2.3 用自带命令行工具冒烟不写代码先确认库没问题源码编出来之后先别急着写 C 代码。打开BUILD_EXAMPLESON再编一次通常能得到一个读条码的命令行工具名字常见的是zxing也可能在build/example子目录下。拿一张二维码图直接跑./build/example/zxing sample_qr.png能输出类似Content: https://example.com这样的结果就说明库本身、图像读取路径和编译链路都是通的。这一步非常值得做。我见过不止一个人把库链接成功但自己代码识别率为 0然后浪费时间怀疑算法其实用命令行工具先把“库没问题”这个前提钉死后面排查范围就只剩自己的调用代码了。手头没有二维码也不怕先用第 4 节的 writer 生成一张再用读工具读回来这就形成了闭环。可以说这是这个方向里的“自举冒烟”一旦跑通后面写业务代码心里就有底。3. zxing-cpp 解码核心接口、四个参数和三种取图方式3.1 最小读码代码ReadBarcode 和 Resultzxing-cpp 的核心解码入口是ReadBarcode它接收一个ImageView和一组DecodeHints返回识别结果。这里最关键的是ImageView它不拥有像素数据只包装内存地址、宽高和颜色格式。也就是说像素数据必须在你手里活到识别结束。最简代码长这样#include zxing/ReadBarcode.h #include iostream #include string #include vector // 自行加载图片到内存可以是灰度也可以是 RGB bool load_image(const std::string path, int width, int height, std::vectorunsigned char outPixels); int main() { int width 0, height 0; std::vectorunsigned char pixels; if (!load_image(test.png, width, height, pixels)) { std::cerr cannot load image\n; return 1; } using namespace zxing; // 用 RGB888 包装像素数据如果是灰度图用 PixelFormat::Lum ImageView image(pixels.data(), width, height, zxing::ImageView::PixelFormat::RGB888); DecodeHints hints; auto result ReadBarcode(image, hints); if (result.isValid()) { std::cout format: ToString(result.format()) \n; std::cout text: TextUtf8(result.text()) \n; } else { std::cout not found\n; } return 0; }load_image这里是我虚拟的辅助函数你可以用自己熟悉的图像加载库实现。zxing-cpp 自己不管读文件所以图片解码这步必须由外部代码完成。把像素包装成ImageView时要注意pixels.data()指向的缓冲区必须是连续内存不能是空的。ReadBarcode的返回值在不同小版本里略有差异。有的版本返回带isValid()的对象有的版本返回指针或std::optional。写代码前先翻一下你那个版本的ReadBarcode.h否则编译时会卡在“找不到成员函数”这种问题上。TextUtf8是把结果文本统一转成 UTF-8 字符串中文内容尤其依赖这个转换。3.2 影响识别率的四个参数TryHarder、格式白名单、TextMode 和旋转DecodeHints是解码行为的控制入口。它不会改变图片但会改变解码器跑的策略和范围。我实际调参时最常用的四个是DecodeHints hints; // 1. 让算法更卖力地找条码 hints.setTryHarder(true); // 2. 只找特定格式减少干扰 hints.setFormats({BarcodeFormat::QRCode, BarcodeFormat::Code128}); // 3. 中文场景下强制按 UTF-8 文本返回 hints.setTextMode(TextMode::Utf8); // 4. 允许自动旋转图像尝试解码 hints.setTryRotate(true); auto result ReadBarcode(image, hints);TryHarder是最直接的“识别率开关”。打开之后解码器会尝试更多扫描路径、更多阈值分割方式对模糊、小尺寸、低对比度图像有明显帮助。代价是耗时可能翻好几倍。我一般不在每帧视频流里默认开只在失败时再开一轮。格式白名单是很多人忽略的一步。默认情况下 zxing-cpp 会尝试所有内置格式格式多了之后误识别率会上升速度也慢。业务场景固定之后比如只扫码枪上传的 Code128那就把 formats 设成只有 Code128。识别率会稳定很多。TextMode决定result.text()返回的字节如何解释。TextMode::Plain返回原始字节流Utf8会强制转成 UTF-8。中文环境里建议用Utf8否则你拿到手的可能是一串乱码似的字节。TryRotate是给“图像方向不确定”的场景准备的。二维码虽然自身有定位角但如果你整体旋转了图像或者手机顺手拍歪了不开旋转往往就失败。一维码更依赖方向开了旋转后对倒置、侧放的条码也能救回来。代价是四个方向各扫一遍速度下降明显。下面是参数选择的一张速查表参数什么时候开什么时候关TryHarder单张图片失败后重试视频流每帧都跑Formats业务格式固定想提速需要从各种图里找任意条码TextMode需要可读文本尤其是中文需要原始字节做协议解析TryRotate用户拍照上传方向随机扫码枪固定角度3.3 从文件、内存和摄像头帧取图有什么不同文件加载看起来最简单但坑也不少。你从 PNG 解码器拿到的像素可能是RGBA也可能是RGB。zxing-cpp 的ImageView有对应的格式枚举但最好在加载时就把它转换成 RGB 或灰度。尤其要小心有些图片库默认返回 4 通道数据你用 3 通道格式去ImageView包装每行字节错位解码结果会非常不稳定。内存数据直接包装是效率最高的路径。比如你已经有一块灰度 Buffer可以直接用PixelFormat::Lum构造ImageView避免一次cvtColor拷贝。摄像头帧的差别主要在行对齐上。很多视频库输出的帧并不是每行紧密排列行尾可能有 padding。如果ImageView不知道每行真正的 stride它就会把第二行的像素往左错位。我第一次接摄像头扫码时就在这里翻过车。正确做法是要把 rowStride 传给ImageView或者先把帧拷贝成一个紧密排列的灰度缓冲区。伪代码示意如下ByteArray grayBuffer(height * width); for (int y 0; y height; y) { for (int x 0; x width; x) { grayBuffer[y * width x] framePixelInGray(y, x); } } ImageView view(grayBuffer, width, height, ImageView::PixelFormat::Lum);用紧密排列的缓冲区可以彻底避开 rowStride 相关的坑。代价是多一次拷贝但换来的是内存布局你完全可控。视频流中这种拷贝开销通常可以接受毕竟解码本身才是大头。4. 生成二维码MultiFormatWriter、PNG 输出和中文编码4.1 从字符串到 BitMatrix 的最小写入流程zxing-cpp 的写码入口是MultiFormatWriter它能生成 QR Code 也能生成一维码。最小流程是设定格式、设定纠错等级然后调用encode得到BitMatrix。BitMatrix是核心输出它本身只是一个二维布尔矩阵true表示这个模块要涂黑。#include zxing/MultiFormatWriter.h #include zxing/BitMatrix.h #include zxing/BarcodeFormat.h int main() { using namespace zxing; MultiFormatWriter writer(BarcodeFormat::QR_CODE); writer.setErrorCorrectionLevel(ErrorCorrectionLevel(ECLevel::L)); writer.setMargin(2); // 静区宽度单位是模块数 BitMatrix matrix writer.encode(https://example.com/check?tokenabc); // matrix.get(x, y) 返回 true表示需要在 (x, y) 处画黑色 return 0; }setMargin在这里尤为重要。QR 规范要求四周至少留 4 个模块的静区不然扫码器很难确认边界。如果你把 margin 设为 0打印出来用手机扫经常会出现“识别不了”或者“识别到但内容不完整”的诡异问题。这属于典型的看起来没问题、实际不能用。ECLevel决定纠错能力。L 是低纠错适合内容短、打印清晰二维码也不会被污染的场景。如果这个码会贴在不光滑的箱子上或者可能被盖住一部分建议选 Q 或 H。纠错等级越高二维码模块越多同样内容生成的图越大。这个取舍要在实际打印前提前想清楚。4.2 把 BitMatrix 落成 PNG/SVG 的两种做法得到BitMatrix只是第一步真正要用还得把它变成位图或矢量图。最直接的做法是把每个模块放大成一个正方形像素块然后交给任意一个图像写出库保存成 PNG。这里我给一段伪代码风格示例int scale 4; int outW matrix.width() * scale; int outH matrix.height() * scale; std::vectorunsigned char img(outW * outH, 255); for (int y 0; y matrix.height(); y) { for (int x 0; x matrix.width(); x) { unsigned char v matrix.get(x, y) ? 0 : 255; for (int dy 0; dy scale; dy) { for (int dx 0; dx scale; dx) { img[(y * scale dy) * outW (x * scale dx)] v; } } } } // 调用你熟悉的图像写出库把 img 保存成灰度 PNG writeGrayPng(qr.png, outW, outH, img.data());scale可以理解为每个模块最终的像素尺寸。打印场景一般取 4 到 6屏幕显示取 1 或 2 就够。放大之后再写 PNG而不是写 PNG 时让库去缩放可以保证每个模块都是一块实心方块不会出现抗锯齿导致的灰边。灰边在扫码器眼里就是噪声。如果目标是网页展示或印刷矢量直接生成 SVG 也挺实用。SVG 本质上就是一堆矩形标签std::string svg svg xmlns\http://www.w3.org/2000/svg\ width\ std::to_string(matrix.width()) \ height\ std::to_string(matrix.height()) \\n; for (int y 0; y matrix.height(); y) { for (int x 0; x matrix.width(); x) { if (matrix.get(x, y)) { svg rect x\ std::to_string(x) \ y\ std::to_string(y) \ width\1\ height\1\ fill\black\/\n; } } } svg /svg\n;这段 SVG 能直接打开也能嵌入 HTML。缺点是大一点的内容模块数量多SVG 文件会非常臃肿。要优化性能先把相邻黑块合并成矩形再输出能把文件体积压到很小。如果只是内部工具用PNG 和 SVG 两种都够不需要引入太重的基础库。4.3 编码中文内容时的踩坑UTF-8 和 ECI中文二维码的坑和编码有关。zxing-cpp 的 writer 在处理字符串时会把内容按 UTF-8 字节序列编码进二维码。问题是二维码读出来时不同扫码器对字节的解释可能不一样。现代手机扫码基本都支持 UTF-8但一些老式扫码终端会默认按本地字符集比如 GBK去解结果就是“你好”变成了乱码。这个问题的典型表现是你用 zxing-cpp 生成再用 zxing-cpp 自己读文本完全正常但换一个扫码设备读出来是“浣犲ソ”这种字节错乱文本。所以我建议分两步验证第一保证你的源码和写入内容确实是 UTF-8不要在业务代码里把字符串从 GBK 转成 UTF-8 之后又转回来。第二业务上如果无法保证所有读取端都支持 UTF-8就需要考虑在二维码里显式写 ECI 段。ECI 是 QR 标准里的扩展标识能让解码端知道后面字节的编码。但很多版本的MultiFormatWriter没有直接暴露 ECI 配置项这个坑在不同版本里表现不一样。如果你那头有对应的底层接口优先用接口设置 UTF-8 ECI没有的话就约束读取端统一按 UTF-8 解。还有一个小提醒中文在 UTF-8 下每字占 3 字节同样字符数能塞进二维码的信息量会比纯英文小很多。我在生成前会先算一下字节长度超过容量就提前报错而不是让 writer 在 encode 时抛异常或者生成一张扫不出的图。按字节数检查是避开这个坑最朴素的方法。5. zxing-cpp 避坑识别不了、链接不上、中文乱码的排查清单5.1 现象二维码横着放就识别失败现象同一张二维码正着放能读旋转 90 度就返回not found。原因TryRotate默认不开启。zxing-cpp 不会自动尝试四个方向除非你在DecodeHints里明确打开旋转扫描。拍照上传类业务里用户拿手机随手一拍方向根本无法保证这个参数不开识别率就开始玩玄学。解决调hints.setTryRotate(true)先试一个批次看识别率是否恢复。如果性能紧张可以考虑在上层通过图像方向矫正把图扶正再跑一次不带旋转的解码但还是让库内部处理更稳。旋转扫描带来的耗时增加比你在外部转图四次再调用四次要小得多。5.2 现象二维码生成出来手机扫出来是乱码现象用MultiFormatWriter生成的内容包含中文生成过程没有异常扫码结果却是字节错位后的乱码。原因写入内容按 UTF-8 进二维码读取端按旧字符集解码。这个问题在中文设备、旧扫码枪、部分浏览器插件上特别常见。解决先把业务内容统一确认是 UTF-8再用TextMode::Utf8读回来验证一遍。如果验证能通过说明 zxing-cpp 自己没问题问题出在外部读取端。极端情况下考虑业务内容改用数字、URL 或拼音开头避免中文直接进二维码。5.3 现象链接一切正常编译链接却报 undefined reference现象target_link_libraries写了ZXing::ZXing头文件也包含到了但链接阶段报undefined reference to zxing::ReadBarcode。原因最常见是 C 标准不够。zxing-cpp 新版本要求 C17而你的主工程可能还在用 C14编译库时头文件内容不同最终导致符号对不上。另一种可能是链接时没有真正链接到安装的那份库而是被其他路径下的同名旧库抢先了。解决先去 CMake 里把全局标准升到 C17set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON)重新 configure再编译。如果还是报 undefined用符号检查命令确认库文件和你包含的头文件是同一来源nm -C libZXing.a | grep ReadBarcode看到的结果是zxing::ReadBarcode这种带命名空间的符号说明库是对的。如果符号里带_ZL或者干脆没有说明库没编对或者版本太旧。5.4 现象带 Alpha 通道的 PNG 解码不出来现象同一张二维码截图保存成 PNG 后识别失败用画图工具转成 JPG 后立刻成功。原因很多图像加载库默认读出来是 RGBA 四通道但你在构造ImageView时如果按 RGB 三通道包装内存里每一行的数据会多出一个字节模型分割全乱。反过来按 RGBA 包装但如果库内部转灰度时没有正确处理 A 通道也会把有效亮度信息带跑偏。解决加载 PNG 后统一转成 RGB 或灰度再交给ImageView。用图像加载库时尽量要求返回三通道或单通道不要手动忽略 alpha。越早丢弃 alpha后面解码越稳定。5.5 现象格式里写着支持 Data Matrix但就是读不出来现象一张非常清晰的 Data Matrix 数据矩阵码用默认参数识别失败把TryHarder打开也不行。原因不同版本对 Data Matrix 的解码实现强弱不一样。另外这类码要求图像中每个模块至少 2 到 3 像素照片如果拍小了模块边缘又被插值糊掉识别率会直线下降。解决先把formats白名单限制成只有BarcodeFormat::DataMatrix排除其他格式的干扰再把图缩放 2 倍到 4 倍重试。缩放时尽量用最近邻插值不要用双线性否则模块边界灰阶更严重。如果原图本身很大问题就变成模块尺寸过小放大也是一个有效方案。6. 把 zxing-cpp 用顺手的几个小技巧视频流、多符号和性能校准6.1 视频流里每帧扫码的三个前置操作实时视频流里识别的压力主要不在 API 调用上而在每帧的图像预处理和参数选择。我自己的习惯是三步走先把彩色帧转成灰度再把图像降到适合解码的宽度通常 640 左右最后把格式白名单固定到业务真正用到的类型。这三步做完每帧耗时能压得很低。DecodeHints最好在循环外构造一次不要在每帧里重复设置TryHarder和 formats。复用同一个 hints 对象可以让解码器内部保留一些缓存结构虽然看起来只是对象复用实际省掉的是反复构造和校验参数的时间。6.2 一张图里多个符号用 ReadBarcodes 而不是循环如果你面对的是一张图里可能出现多个 QR Code 或一维码用ReadBarcode只会返回第一个。zxing-cpp 提供了复数接口ReadBarcodes返回一个结果列表。多符号场景下截图、批量扫描、货架盘点都有用。用多符号接口时要注意返回结果数量要和你业务预期一致。有时候一个角标、一个 logo 也会被认为是符号反而干扰业务。解决办法还是格式白名单把不相关的格式全部关掉。6.3 参数调整顺序和验证习惯参数不是一次性全开的。我一般按这个顺序试先限格式再缩放图像到合适模块尺寸接着开TryRotate最后才上TryHarder。顺序反过来最容易把 CPU 打满但识别率没提升多少因为问题根本不在算法狠不狠而在图还没喂对。代码写完后我会把一批测试图放进目录批量跑一遍统计“识别条码数 / 正确条码数 / 耗时中位数”。这个黑盒测试看似简单却能暴露大多数玄学问题。比如某张图在调试器里能读发布版就失败多数是优化开关或未初始化内存的问题。做二维码生成时也一样生成完立刻用 zxing-cpp 自己读一遍。自己能读回来再拿手机和各种扫码终端试。能通过自己 recycler 的码在真实相机里大概率也能通过。这是我多次踩坑之后养成的习惯先锁死库本身再排查外界变量很多看似神秘的问题到最后都是最普通的原因。这个方向值不值得投入取决于你是不是真的在 C 工程里需要原生的扫码解码能力。如果只是做一个内部工具zxing-cpp 这套体系足够撑住如果要做高速视频流就要把参数取舍和图像预处理当成优化重点。希望帮到你。本文还有配套的精品资源点击获取