简介面向程序开发者的二维码生成动态库同时支持 QR-Code 与 Data-Matrix 两种主流码制解决在自有系统中快速集成二维码生成能力的痛点。包内提供 DLL、LIB、H 文件开发者可按需调用 QR_Code 与 Data_Matrix 两个函数接口传入文本和保存路径即可输出 BMP 图片适合桌面工具、管理系统或硬件配套场景。资源共 11 个文件压缩包约 2.26MB包含 5 个动态库、3 个头文件、2 个导入库及 1 个附赠示例程序结构紧凑便于直接引用和二次开发。此外随包附赠“QR二维码开发组件”博客整理和二维码生成小软件既有接口说明又有可视化工具可辅助调试和快速出图。目前已有 2680 人学习下载对于需要低成本实现二维码输出的开发者来说是一份实用参考。1. 二维码库项目解析两种码制一个入口离线生成也能定制做追溯系统的开发者应该都遇到过这种需求同一条业务数据既要生成供手机扫码的QR码又要生成供工业扫码枪识别的DataMatrix码。这个生成二维码库把QR-Code和Data-Matrix两套编码器整合在同一个包入口下脱离第三方在线API纯本地计算后输出PNG或SVG。刚拆源码时我有个反直觉的发现DataMatrix的ECC200纠错实现比QR的里德-所罗门更繁琐很多现成生成器只做QR遇到DataMatrix就只能临时换依赖而这个项目把两种码制的编码链路完整放在了一起。适合离线批量生成标签、打印追溯码、二次定制输出格式的开发者不需要懂底层纠错算法也能跑通。2. 架构与目录编码层、纠错层、渲染层的三层分工2.1 目录结构每个文件管什么拿到源码第一件事我会先看目录布局而不是直接跑demo。这个库包名是qrdm下面按码制分成qr和dm两个子包再单独抽一个render目录做图像输出顶层放examples和tests一眼能看出模块边界qrdm/ ├── __init__.py ├── cli.py ├── models.py ├── qr/ │ ├── encoder.py # QR数据编码、版本选择 │ ├── reedsolomon.py # 里德-所罗门纠错码 │ ├── mask.py # 8种掩码与惩罚分评估 │ └── matrix.py # QR码元矩阵构造 ├── dm/ │ ├── encoder.py # DataMatrix编码与符号尺寸选择 │ └── ecc200.py # ECC200纠错计算 ├── render/ │ ├── png.py # 像素级位图输出 │ └── svg.py # 矢量路径输出 └── utils.py # 伽罗华域乘法等公共函数qr子包没有把编码逻辑写进一个文件而是拆成encoder、reedsolomon、mask、matrix四个模块。encoder管输入文本转码和版本选择reedsolomon只做纠错码计算mask撑起QR最耗时的掩码评估matrix负责在逻辑坐标系里放置功能图形和数据码字。dm子包结构类似encoder做数据编码和符号尺寸选择ecc200实现ECC200纠错。render目录和qr/dm之间没有业务依赖两个渲染器都只认Matrix这个布尔矩阵。依赖设计上png.py用Pillow画矩形svg.py用纯字符串拼矢量路径cli.py用标准库argparse而不是click这样可以减少第三方依赖数量。离线环境只要装上Pillow就能跑编码和纠错部分完全不依赖外部库。tests目录里放了roundtrip测试核心思路是生成矩阵后直接比对固定样本的码字序列而不是生成图后拿扫码枪识别因为扫码依赖外部工具不适合写进自动化测试。examples目录里的batch_generate.py和embed_logo.py是二次开发的基础模板改Logo位置、改批量字段都可以以它们为起点。2.2 核心数据结构码元矩阵与位图缓冲区整个库最关键的数据结构是Matrix编码器输出它渲染器消费它。它就是一个二维布尔数组True代表深色模块False代表浅色模块。这个类定义在models.py里class Matrix: def __init__(self, size): self.size size self._cells [[False] * size for _ in range(size)] def set(self, row, col, valueTrue): if 0 row self.size and 0 col self.size: self._cells[row][col] value def flip(self, row, col): self._cells[row][col] not self._cells[row][col] def get_rows(self): return [row[:] for row in self._cells] def expand(self, factor): new_size self.size * factor new Matrix(new_size) for r in range(self.size): for c in range(self.size): if self._cells[r][c]: base_r, base_c r * factor, c * factor for dr in range(factor): for dc in range(factor): new.set(base_r dr, base_c dc, True) return newset负责写入码元带边界保护越界时静默忽略。flip负责翻转模块这看起来简单但作用很大。get_rows返回的是行副本渲染层用副本可以避免编码器后续操作污染已经生成的矩阵。expand把一个逻辑模块放大成factor乘factor的物理像素块渲染前先expand让编码器的输出与最终图像的缩放比例彻底解耦。保留flip而不是用set(true/false)替代是因为QR掩码阶段需要对整个区域做上千次翻转如果每次都重新构造列表大版本QR会创建大量临时对象批量生成时GC压力很明显。DataMatrix的蛇形映射也依赖set的静默越界特性映射路径扫到寻轨图形占用的位置时直接跳过不需要每次判断边界。批量缓存场景下Matrix还有serialize方法把二维布尔矩阵展成元组方便作为缓存键这是第5章lru_cache的前置条件。2.3 QR与DataMatrix在设计上的核心差异两种码经常被放在一起提但底层设计差异很大选错码制会给下游识别和设备兼容性带来麻烦。这里列一下这个项目里最常被问到的差异点对比项QR CodeDataMatrix外观三个角有回字形定位图案L型实线边框加另两侧虚线纠错算法里德-所罗门分块纠错ECC200里德-所罗门变体纠错级别L/M/Q/H四档默认固定纠错最小尺寸21x21模块10x10模块适用场景营销、支付、带Logo工业标签、微小物体直接标记QR的优势是内容容量大、有四级纠错可以选择适合营销物料和需要贴Logo的场景DataMatrix的优势是最小尺寸只有10x10模块适合电路板和微小包装上的激光打标。从编码实现来说QR最啰嗦的是版本表、分块表和掩码评估DataMatrix最模糊的是符号尺寸与数据区域映射规则两者共用字节转码和GF域乘法工具但纠错参数不同。如果项目只是给供应链打印追溯码直接选DM更稳工业扫码枪对DM的支持最统一如果面向C端用户扫码打开页面QR是唯一合理选择手机相机原生就能识别QR但多数不认DM。这个库把两种码制都做进来从架构上就规避了临时换库的尴尬。我的习惯是固定短数据用DM频繁变长的文本用QR版本自动选择能省掉不少人工判断。3. 核心模块拆解从输入字符串到像素矩阵的完整链路3.1 QR码编码主流程模式选择与里德-所罗门纠错QR的编码入口在qr/encoder.py整体流程是把输入字符串按UTF-8转字节流查容量表选出最小版本按版本和纠错级别分块对每块做里德-所罗门纠错再交织所有码字最后填入码元矩阵并执行掩码。主流程如下def encode_qr(text: str, ecl: str M) - Matrix: data_bytes encode_text_to_bytes(text) version select_version(len(data_bytes), ecl) blocks build_rs_blocks(version, ecl) result_codewords [] for block in blocks: data_cw data_bytes[block.offset: block.offset block.data_len] ecc_cw rs_generate(data_cw, block.ecc_len) result_codewords.extend(interleave(data_cw, ecc_cw)) matrix init_matrix(version) place_function_patterns(matrix, version) place_data_codewords(matrix, result_codewords, version) mask select_best_mask(matrix, version, ecl) apply_mask(matrix, mask) add_quiet_zone(matrix, 4) return matrixencode_text_to_bytes统一用UTF-8避免后续扫码端按GBK解码出现乱码select_version查的是QR规范容量表内容超过当前版本容量就升一版超过40抛异常。build_rs_blocks按QR分块规则把数据切成多个块每个块带独立的纠错码字这样局部脏污不会拖垮整张码。interleave是QR特有的交织步骤把多块纠错后的码字交错排列目的是让突发错误分散到不同块里。参数说明text是业务字符串ecl是纠错等级默认M可选L、M、Q、H。L大约能恢复7%的码字损失H能恢复约30%但容量几乎减半。如果要在二维码中心贴Logo我一般会强制升到H因为中心区域被遮挡后要靠多余纠错容量把原始数据捞回来。3.2 里德-所罗门纠错的工程实现RS纠错是二维码生成里最容易翻车的部分很多二开的人以为把数据位直接丢给多项式就完事结果扫码永远提示格式不支持。关键在于QR在GF(2^8)伽罗华域上运算生成多项式随ecc_len变化偷懒写固定多项式的代码碰到小版本就会算出错误码字。这个库的实现放在qr/reedsolomon.pyfrom qrdm.utils import gf_mul def rs_generate(data: list[int], ecc_len: int) - list[int]: gen rs_generator_poly(ecc_len, prim0x11d, fcr0) res data [0] * ecc_len for i in range(len(data)): coef res[i] if coef 0: continue for j in range(1, len(gen)): res[i j] ^ gf_mul(gen[j], coef, prim0x11d, fcr0) return res[-ecc_len:]逻辑说明rs_generator_poly根据ecc_len动态生成多项式0x11d是QR规定的本原多项式fcr是第一个根起始指数QR用0DataMatrix的ECC200用1所以这个参数必须能配置。外层循环每处理一个数据字节就用当前系数乘生成多项式并异或到后续码字上最后取末尾ecc_len个字节作为纠错码。gf_mul是伽罗华域乘法内部要做模0x11d的规约不能用普通整数乘法替代。参数说明data是输入码字列表ecc_len是纠错码字数由分块表查出来。prim和fcr是工程参数同一个数学工具函数可以复用于QR和DataMatrix只是传参不同。如果改错prim生成的码字表面看起来规律但扫码枪会直接判定数据校验失败这一类的bug最难查因为普通图片浏览看不出任何异常。3.3 DataMatrix编码主流程ECC200与数据区域映射DataMatrix入口在dm/encoder.py流程比QR简单先按ECC200规则做数据编码选符号尺寸计算纠错码然后在L型边框内部做蛇形映射。核心流程如下def encode_dm(text: str) - Matrix: data_words dm_encode_text(text) symbol_size select_symbol_size(len(data_words)) ecc_words ecc200_compute(data_words, symbol_size) matrix Matrix(symbol_size) place_codewords(matrix, data_words ecc_words, symbol_size) add_finder_patterns(matrix) return matrixdm_encode_text把文本转成ECC200码字序列数字和文本有专用压缩模式纯ASCII直接用基本码字其他字符走扩展ASCII映射。select_symbol_size查表返回从10x10到144x144的符号边长按数据码字数量选最小尺寸。ecc200_compute是ECC200纠错核心它和QR的RS区别在于生成多项式参数不同起始根参数也随尺寸变化所以不能直接复用qr/reedsolomon.py里的默认参数必须把prim和fcr抽成可传参数。参数说明data_words是数据码字列表symbol_size决定矩阵边长和纠错码数量。place_codewords是DataMatrix最考验细节的地方码字按蛇形路径从左上角填入数据区遇到寻轨图形占用的位置要跳过。映射不对的直接后果是生成出来的图案尺寸正确但扫码枪无法识别这类bug没有黑盒调试手段只能对照规范里的映射表逐格核对。3.4 渲染后端布尔矩阵转PNG的像素级实现渲染层是唯一接触真实图像的地方。render/png.py接收Matrix实例和一组渲染参数输出Pillow的Image对象。核心实现很直接def render_png(matrix: Matrix, module_size4, quiet_zone4, foreground(0, 0, 0), background(255, 255, 255)): side matrix.size border quiet_zone * module_size size side * module_size border * 2 img Image.new(RGB, (size, size), background) draw ImageDraw.Draw(img) for row in range(side): for col in range(side): if matrix.is_set(row, col): x0 border col * module_size y0 border row * module_size draw.rectangle([x0, y0, x0 module_size - 1, y0 module_size - 1], fillforeground) return img先一次性算出整张位图的物理边长避免逐行resize产生锯齿。遍历逻辑矩阵的每个模块只要为True就按module_size画一个实心矩形坐标是左上角加静区偏移。这里用模块坐标直接乘module_size而不是先expand矩阵再整图缩放因为Pillow整图缩放会引入灰度插值印刷后浅色边缘发虚扫码率会直线下降。参数说明module_size是每个逻辑模块对应的物理像素数默认4印刷场景不建议小于4quiet_zone是静区模块数QR规范要求不小于4DataMatrix规范规定默认1但实际打印建议至少2foreground和background是RGB三元组注意不要用带透明通道的颜色RGBA直接丢给印刷会变成白底黑块。svg.py用同样的遍历逻辑拼矢量路径一条path能合并大量矩形体积比PNG小很多。4. 运行与排查命令行参数、批量生成与高频翻车点4.1 环境准备与安装依赖这个库定位是轻量离线库运行时只需要Pillow一个第三方依赖其他全部用Python标准库。Python版本要求3.9以上主要是用到了list[int]类型注解3.8也能跑只是会报类型注解相关警告。安装依赖pip install -r requirements.txtrequirements.txt里只有Pillow一行不需要numpy和scipy。断网的生产环境部署时提前下载Pillow的wheel包然后执行pip install --no-index --find-links./offline_pkgs Pillow。装完执行python -m qrdm.cli --help能正常打印参数说明就代表环境没问题。我一般会在虚拟环境里装避免和系统里的图像库冲突。Pillow版本差异偶尔会让PNG压缩级别不同但模块布局不变扫码结果一致。4.2 命令行参数详解命令行入口支持单张生成和批量生成两种工作方式。直接看命令比看文档更快qrdm gen -t https://example.com -f qr -o order_qr.png -s 6 -e M -q 4 qrdm gen -t SN2409120001 -f dm -o label_dm.png -s 4 -e M -q 4 qrdm batch -i batch.csv -d ./out_dir -f qr --format png参数表如下参数含义默认值说明-t/--text待编码内容无必填超长内容会报版本超限-f/--formatqr或dmqr码制选择-s/--module-size模块像素大小4印刷建议4-6-e/--error纠错等级MQR有效值是L/M/Q/HDM固定传M即可-q/--quiet-zone静区模块数4建议不要小于2-o/--output输出文件路径out.png按后缀自动判断PNG或SVG-i/--input批量CSV路径无配合batch子命令表格里这7个参数覆盖了90%的使用场景。需要注意--error参数对DataMatrix没有实际意义因为ECC200纠错容量固定接口保留它是为了不增加校验分支。批量模式CSV至少要有content列可选type列指定码制可选sn列作为输出文件名没有sn就用行号。4.3 编程接口调用示例命令行适合一次性任务集成进业务系统还是要用Python接口。生成单张二维码只需要三步调generate_matrix得到Matrix调render_png得到Image最后save落盘from qrdm import generate_matrix from qrdm.render import render_png matrix generate_matrix(SN2409120001, code_typedm, error_levelM) img render_png(matrix, module_size6, quiet_zone4) img.save(label_dm.png, dpi(300, 300))批量生成场景更常见的是从ERP导出CSV后循环生成标签。CodeType枚举同时支持字符串传入所以批量代码很短import csv from qrdm import generate_matrix from qrdm.render import render_png with open(batch.csv, encodingutf-8-sig) as f: reader csv.DictReader(f) for i, row in enumerate(reader): mat generate_matrix(row[content], code_typerow.get(type, qr)) img render_png(mat, module_size4, quiet_zone4) out row.get(sn, fimg_{i}) img.save(f{out}.png, dpi(300, 300))csv.DictReader把表头变字段名encoding用utf-8-sig是为了兼容Excel导出的带BOM文件不然第一列列名会变成\uFEFFcontent导致KeyError。generate_matrix和render_png分离的接口设计允许业务层先缓存Matrix再针对不同物理尺寸渲染多份图片避免重复编码计算。row.get(type, qr)让老CSV文件只保留content列也能跑不用修改历史数据。4.4 高频踩坑记录尺寸异常、乱码与扫码不识别这里记录的是实际使用中翻车过的几个问题每条都按现象、原因、解决三个维度写清楚。现象一生成的DataMatrix在部分扫码枪上识别很慢要凑很近才能扫出。原因是module_size只有1静区虽然默认4但热敏纸受热后墨点扩散模块边界糊成一团。解决module_size提到4到6静区在热敏纸场景直接给到4不要迷信DM规范里1个模块静区的下限。现象二QR码内容带中文和特殊符号生成后部分手机扫出来乱码。原因是encode_text_to_bytes用UTF-8但早期扫码App会按GBK猜编码。解决保持UTF-8不变不做编码探测如果业务必须兼容老设备把内容先UTF-8再Base64加约定前缀让后端识别。现象三批量生成几千张后内存涨到被系统杀掉。原因是render_png返回的Image对象全部堆在循环里没有及时释放引用。解决save完立即img.close()把局部变量置空循环外用gc.collect()兜底避免Pillow底层解码器残留引用。现象四SVG输出在AI里放大500%没问题但印刷厂出的PDF里边缘有细毛边。原因是SVG把每个模块画成独立rect矢量软件做透明度叠加时把相邻矩形边缘算成了反锯齿。解决调用svg.py时传入merge_pathsTrue让渲染后端把所有深色矩形合并成单个path指令边缘干净且文件体积小一半以上。现象五内容长度超出当前纠错等级容量抛异常但报错信息只说data too long。原因是select_version查容量表时只给总额度没算分块后的字节损耗。解决改异常文案带上建议版本和降低后的纠错等级比如“Content 200 bytes exceeds M capacity of version 6, try error L or version 7”。这五条覆盖了项目运行中最常见的失败路径。前三条影响生产后两条影响输出质量。排查顺序建议先看矩阵尺寸是否正确再校验模块大小和静区最后用扫码枪做端到端确认。5. 性能与图像细节批量提速、扫码率与文件体积的平衡5.1 编码结果缓存与批量流水线二维码生成是典型的CPU密集加重复劳动。同一个产品编号如果只是换输出尺寸QR的矩阵计算结果完全一致没必要重新跑一遍里德-所罗门。我在__init__.py的generate_matrix入口处加了lru_cache缓存from functools import lru_cache lru_cache(maxsize1024) def generate_matrix(text: str, code_type: str, error_level: str) - tuple: if code_type qr: mat encode_qr(text, error_level) else: mat encode_dm(text) return mat.serialize()serialize把矩阵展开成扁平元组因为lru_cache要求参数和返回值都是可哈希类型直接缓存Matrix对象会导致引用泄漏。渲染前调用deserialize还原成Matrix再走render_png。maxsize1024意味着同时最多缓存1024个不同内容的矩阵超出后自动淘汰最老的条目。参数说明里error_level对DM是固定值M但保留这个参数可以让缓存键区分不同纠错级别的QR。批量模式下我习惯用multiprocessing而不是多线程因为QR编码是纯Python计算多线程受GIL限制提升有限进程池反而能线性扩展。一个经验值四核机器批量生成5000张PNG八个worker比单进程快三倍多瓶颈主要在PNG压缩而不是编码计算。worker数量建议用os.cpu_count()减1避免和主进程抢CPU导致系统卡顿。5.2 module_size与静区对扫码率的影响模块尺寸的选择不是越大越好而是看输出介质的物理精度。屏幕显示用2到4个像素就够印刷标签先算物理尺寸再决定标签要求20mm见方打印机305dpi单个模块物理宽度约0.5mmmodule_size取打印分辨率除以模块密度即可。常用参考输出介质推荐module_size静区模块数手机屏幕显示2-44桌面激光打印机4-64热敏标签机203dpi5-84304dpi工业打标4-62-4高精喷码2-42这个表只是起点真正决定扫码率的是打印后模块边界是否清晰。热敏纸受热会扩散module_size取偏大金属激光雕刻精度高但打标深度不够时反射对比度过低也容易识别失败。渲染层提供contrast参数来扩大前景和背景的亮度差工业场景foreground设纯黑、background设纯白不要用灰色背景强光下反光会导致扫描不出。quiet_zone不是装饰性留白而是扫码算法的寻像基准。QR的定位图案要靠静区与周围环境的反差来锁定如果静区混入其他印刷图案扫码枪会在全图中找到多个候选区域解码时间会剧烈跳动。批量生成模板时我会把静区直接画进标签模板背景里而不是依赖贴标签后再人工留白。5.3 SVG矢量输出与文件体积优化PNG是位图放大后模块边缘由像素插值决定印刷时如果设计稿把二维码拉得太大边缘会很模糊。SVG矢量输出把每个模块变成坐标指令任意缩放不变形适合嵌入高分辨率印刷稿。render/svg.py核心逻辑是遍历矩阵把同一行的连续深色模块合并成横线def render_svg(matrix: Matrix, module_size1, quiet_zone4) - str: parts [] border quiet_zone for row in range(matrix.size): col 0 while col matrix.size: if matrix.is_set(row, col): start col while col matrix.size and matrix.is_set(row, col): col 1 x border start y border row w col - start parts.append(fM{x} {y}h{w}v1h-{w}z) else: col 1 path .join(parts) return fsvg xmlnshttp://www.w3.org/2000/svg viewBox0 0 {matrix.size border*2} {matrix.size border*2}path d{path}//svg这个实现把每行连续深色模块合并成一个水平矩形路径M移动到起点h画横线v画竖线h-再闭合比每个模块单独输出rect至少减少三分之二的指令数量。viewBox直接按矩阵边长加静区算好不依赖物理像素值矢量软件缩放时不会失真。参数说明里module_size对SVG没有意义因为矢量单位是坐标值而不是像素保留这个参数是为了统一渲染接口签名传1即可。SVG写出后建议再做一次路径压缩把相邻行相同起点和相同长度的矩形合并成垂直方向的竖块。这个优化在QR这种规则图案上效果明显一张版本10的QR码不优化约3000条路径指令优化后不到500条文件体积可以压到原来的五分之一左右。注意SVG内容里如果出现与符号会破坏XML结构渲染前要做转义处理这是二次开发最容易漏掉的细节。6. 二次开发实战Logo水印、自定义码制接入与回归验证6.1 嵌入Logo的改造思路最常见的定制需求是给二维码中心加Logo。改造点不在渲染层而在编码前的纠错等级选择。中心区域大约占矩阵面积的9%到15%Logo遮挡后必须提前用高纠错等级让数据容忍这部分码字损失from qrdm import generate_matrix from qrdm.render import render_png from PIL import Image def generate_with_logo(text: str, logo_path: str, module_size6) - Image: matrix generate_matrix(text, code_typeqr, error_levelH) img render_png(matrix, module_sizemodule_size, quiet_zone4) matrix_size matrix.size * module_size logo Image.open(logo_path) logo.thumbnail((int(matrix_size * 0.2), int(matrix_size * 0.2))) offset ((img.width - logo.width) // 2, (img.height - logo.height) // 2) img.paste(logo, offset, masklogo if logo.mode RGBA else None) return imgerror_level强制H是为了在中心遮挡近两成模块后仍能恢复数据。logo缩放到矩阵总尺寸的20%过大遮挡比例超标过小影响品牌展示。paste加mask保留透明背景如果logo是JPG没有透明通道mask传None会在四周留下矩形白底最好让设计提前交付PNG格式Logo。这个改造没有动编码器原有缓存策略依然生效。6.2 新增码制的接入点如果业务要求追加PDF417接入点很清晰在models.py的CodeType枚举里加一项在generate_matrix里加elif分支仿照dm子包新建pdf417目录实现编码和布局。渲染层完全不用改因为Matrix和render_png之间只有一个布尔矩阵协议。新码制的纠错算法不能简单复制QR的RS代码各码制对伽罗华域参数要求差异很大至少要确认prim和fcr两个值是否一致。6.3 回归验证与日常习惯从那以后我每次给生成库新增码制或调整参数都会强制走一遍验证清单先用一条固定字符串生成样本在三种不同尺寸和两种背景色下肉眼检查再用扫码App和桌面扫码枪各扫一次最后用小尺寸低对比度的极端组合再跑一遍确认不会出现截图看着正常、现场却扫不出来的情况。这套流程给项目省了返工损失希望帮到你。本文还有配套的精品资源点击获取