最近在做一个物联网设备的数据展示项目需要将设备ID和实时状态信息生成二维码方便移动端扫码快速获取。最初尝试了几个在线生成工具但涉及到设备数据频繁更新和离线使用的需求在线方案显然不够灵活。于是我决定动手实现一个本地的“文本二维码生成器”。这个工具不仅解决了我的项目需求其核心思路——将任意文本信息编码为二维码图像——在嵌入式开发如STM32显示、数据交换、简易加密等场景下都非常实用。本文将手把手带你从零实现一个功能完整的文本转二维码工具涵盖核心库选型、环境搭建、代码编写、参数调优到最终集成并提供可直接复用的完整代码示例。1. 二维码技术背景与核心概念在深入代码之前我们有必要厘清几个核心概念这有助于理解后续的每一步操作。二维码QR Code是一种矩阵式二维条码。与我们常见的一维条形码只在一个方向上存储信息不同二维码在水平和垂直两个方向上都存储信息因此容量更大且具备纠错能力。它本质上是一种将二进制数据包括数字、字母、汉字等编码成黑白方块图案的图形化方案。一个完整的二维码生成过程包含以下几个关键环节数据编码将输入文本如URL、字符串按照特定规则如数字模式、字母数字模式、字节模式等转换为二进制位流。纠错编码为了提高容错率即使二维码部分污损仍可识别会使用如里德-所罗门Reed-Solomon等算法为原始数据添加纠错码字。结构生成将编码后的数据与纠错码字按照二维码标准填充到特定大小的矩阵中并添加定位图案、校正图形、格式信息、版本信息等必要元素。掩模为了优化二维码的识别率避免出现大面积空白或黑块影响扫描器判断会对数据区域应用8种预定义的掩模规则之一并选择最优结果。渲染输出将最终的二进制矩阵0和1渲染为可视化的黑白图像并可选择添加边距、颜色、Logo等。对于开发者而言我们无需从头实现这套复杂的算法。社区已有许多成熟、高效的库可供使用。在Python生态中qrcode库因其简单易用、功能全面而广受欢迎。它内部依赖于PillowPIL库进行图像处理。因此我们的“文本二维码生成器”将基于qrcodePillow这套黄金组合来构建。2. 环境准备与项目初始化我们的目标是创建一个跨平台的命令行/脚本工具因此选择Python作为开发语言。下面开始搭建开发环境。2.1 安装Python与包管理工具确保你的系统已安装Python 3.6或更高版本。可以通过命令行验证python --version # 或 python3 --version推荐使用pip作为包管理工具。通常它随Python一同安装。2.2 创建虚拟环境与安装依赖为了避免污染系统环境并为项目创建独立的依赖空间我们使用虚拟环境。# 1. 为项目创建一个新目录并进入 mkdir text_qr_generator cd text_qr_generator # 2. 创建虚拟环境以venv为例 python -m venv venv # 3. 激活虚拟环境 # 在 Windows 上 venv\Scripts\activate # 在 macOS/Linux 上 source venv/bin/activate # 激活后命令行提示符前通常会显示 (venv)激活虚拟环境后安装核心依赖库pip install qrcode[pil] pillow这里使用qrcode[pil]这种写法它会自动安装qrcode库及其对Pillow的额外支持用于生成图片。Pillow是Python图像处理的事实标准库。2.3 验证安装与项目结构安装完成后可以快速验证一下python -c import qrcode, PIL; print(QRCode version:, qrcode.__version__, PIL version:, PIL.__version__)如果输出版本号且无报错说明环境配置成功。接下来规划一下我们项目的简单结构text_qr_generator/ ├── venv/ # 虚拟环境目录.gitignore忽略 ├── qr_generator.py # 主程序脚本 ├── requirements.txt # 依赖列表 └── output/ # 用于存放生成的二维码图片创建requirements.txt文件记录依赖及其版本便于他人复现环境# 生成 requirements.txt pip freeze requirements.txt此时requirements.txt内容应包含qrcode和Pillow等。3. 核心库qrcode快速上手与参数详解在编写完整工具前我们先通过几个简单的例子快速掌握qrcode库的核心API和关键参数。3.1 最简单的二维码生成创建一个最简单的脚本simple_demo.pyimport qrcode # 要编码的文本内容 data https://www.csdn.net # 创建QRCode对象 qr qrcode.QRCode( version1, # 控制二维码大小1-40值越大码点越密存储信息越多。设为None则自动确定最小版本。 error_correctionqrcode.constants.ERROR_CORRECT_L, # 纠错等级 box_size10, # 每个小方块包含的像素数 border4, # 二维码与图片边界的距离单位为小方块数 ) # 添加数据 qr.add_data(data) # 生成二维码矩阵 qr.make(fitTrue) # 创建并保存图像 img qr.make_image(fill_colorblack, back_colorwhite) img.save(simple_qr.png) print(二维码已生成simple_qr.png)运行此脚本会在当前目录生成一个包含CSDN网址的二维码图片。用手机扫码即可跳转。3.2 关键参数深度解析version(版本)范围1到40。版本1是21x21的矩阵版本40是177x177的矩阵。每增加一个版本每边增加4个模块。fitTrue的作用当version设为None或调用make(fitTrue)时库会自动计算能够容纳所提供数据的最小版本。这是最常用的方式可以避免因版本设置过小导致数据无法编码。error_correction(纠错等级)这是一个至关重要的参数决定了二维码的抗损毁能力。qrcode.constants提供了四个等级ERROR_CORRECT_L(L级): 约可恢复7%的数据错误。ERROR_CORRECT_M(M级): 约可恢复15%的数据错误。这是默认等级也是大多数场景的推荐选择。ERROR_CORRECT_Q(Q级): 约可恢复25%的数据错误。ERROR_CORRECT_H(H级): 约可恢复30%的数据错误。等级越高容错能力越强但生成的二维码图案也更复杂数据密度更高。如果需要在小尺寸打印或可能磨损的场合使用建议使用H级。box_size与border(尺寸与边距)box_size: 每个“黑点”或“白点”模块在最终图像中的像素大小。增大此值会等比例放大整个二维码图片的物理尺寸但不会增加其信息容量。border: 二维码有效区域与图片边缘的空白边距单位是模块数。标准规定最小边距为4个模块。不建议设置为0否则许多扫码器可能无法识别。make_image方法fill_color: 二维码点的颜色默认black。back_color: 背景颜色默认white。你可以使用标准的颜色名称如red,blue或十六进制字符串如#FF5733。3.3 进阶功能添加Logo与样式调整一个常见的需求是在二维码中央嵌入Logo。这需要用到PIL库的图像处理功能。import qrcode from PIL import Image def generate_qr_with_logo(data, logo_path, output_path): # 生成基础二维码 qr qrcode.QRCode( error_correctionqrcode.constants.ERROR_CORRECT_H # 使用高纠错等级为Logo预留空间 ) qr.add_data(data) qr.make(fitTrue) # 生成黑白二维码图片 qr_img qr.make_image(fill_color#2C3E50, back_color#ECF0F1).convert(RGB) # 打开并处理Logo logo Image.open(logo_path) # 计算Logo的合适大小例如二维码大小的1/4 qr_width, qr_height qr_img.size logo_size qr_width // 4 # 调整Logo大小保持宽高比 logo.thumbnail((logo_size, logo_size), Image.Resampling.LANCZOS) # 计算Logo粘贴的位置居中 pos ((qr_width - logo.size[0]) // 2, (qr_height - logo.size[1]) // 2) # 将Logo粘贴到二维码中央 qr_img.paste(logo, pos) # 保存最终图片 qr_img.save(output_path) print(f带Logo的二维码已生成{output_path}) # 使用示例 generate_qr_with_logo(Hello, CSDN!, path/to/your/logo.png, qr_with_logo.png)注意添加Logo会覆盖部分二维码数据因此务必使用较高的纠错等级如H级以确保二维码即使被部分遮挡仍可被正确识别。4. 完整实战构建命令行文本二维码生成器现在我们将上述知识整合构建一个功能相对完整的命令行工具。这个工具将支持以下功能指定输出的文本内容。指定输出图片的文件名和格式PNG, JPG等。可选设置二维码尺寸、纠错等级、颜色。可选在二维码中央添加Logo。4.1 创建主程序文件qr_generator.py#!/usr/bin/env python3 文本二维码生成器 - 命令行工具 支持自定义尺寸、纠错等级、颜色、Logo嵌入。 import argparse import os import sys import qrcode from PIL import Image, ImageDraw, ImageFont from qrcode.constants import ERROR_CORRECT_L, ERROR_CORRECT_M, ERROR_CORRECT_Q, ERROR_CORRECT_H # 纠错等级映射字典 ERROR_CORRECTION_MAP { L: ERROR_CORRECT_L, M: ERROR_CORRECT_M, Q: ERROR_CORRECT_Q, H: ERROR_CORRECT_H, } def create_qr_code(data, output_file, **kwargs): 核心函数创建二维码并保存。 参数: data (str): 要编码的文本。 output_file (str): 输出图片路径。 **kwargs: 其他可选参数包括 version (int): 二维码版本。 error_correction (str): 纠错等级 (L,M,Q,H)。 box_size (int): 模块像素大小。 border (int): 边距模块数。 fill_color (str): 前景色。 back_color (str): 背景色。 logo (str): Logo图片路径。 label (str): 底部标签文字。 # 解析参数设置默认值 version kwargs.get(version, None) error_correction ERROR_CORRECTION_MAP.get(kwargs.get(error_correction, M).upper(), ERROR_CORRECT_M) box_size kwargs.get(box_size, 10) border kwargs.get(border, 4) fill_color kwargs.get(fill_color, black) back_color kwargs.get(back_color, white) logo_path kwargs.get(logo, None) label_text kwargs.get(label, None) # 1. 创建QRCode对象并生成基础二维码 print(f正在生成二维码内容长度: {len(data)} 字符...) qr qrcode.QRCode( versionversion, error_correctionerror_correction, box_sizebox_size, borderborder, ) qr.add_data(data) qr.make(fitTrue) # fitTrue 自动确定最小版本 # 2. 生成初始图像 qr_img qr.make_image(fill_colorfill_color, back_colorback_color).convert(RGB) # 3. 可选添加Logo if logo_path and os.path.exists(logo_path): print(f正在添加Logo: {logo_path}) try: logo Image.open(logo_path) # 计算Logo大小例如二维码宽度的1/5 qr_width, qr_height qr_img.size logo_max_size qr_width // 5 logo.thumbnail((logo_max_size, logo_max_size), Image.Resampling.LANCZOS) # 计算粘贴位置居中 logo_pos ((qr_width - logo.size[0]) // 2, (qr_height - logo.size[1]) // 2) # 创建一个与Logo大小相同的白色背景圆角矩形可选使Logo更清晰 logo_bg_size (logo.size[0] 10, logo.size[1] 10) logo_bg Image.new(RGB, logo_bg_size, back_color) mask Image.new(L, logo_bg_size, 0) draw_mask ImageDraw.Draw(mask) draw_mask.rounded_rectangle([(0,0), logo_bg_size], radius15, fill255) # 将圆角矩形背景粘贴到二维码上 bg_pos (logo_pos[0]-5, logo_pos[1]-5) qr_img.paste(logo_bg, bg_pos, maskmask) # 将Logo粘贴到背景上 qr_img.paste(logo, logo_pos, masklogo) # 使用Logo自身作为蒙版处理透明背景 except Exception as e: print(f警告添加Logo失败 - {e}. 将继续生成无Logo二维码。) # 4. 可选添加底部文字标签 if label_text: print(f正在添加标签: {label_text}) try: # 扩展画布以容纳文字 img_with_border Image.new(RGB, (qr_img.width, qr_img.height 40), back_color) img_with_border.paste(qr_img, (0, 0)) # 添加文字需要字体文件这里使用默认字体可能不美观 draw ImageDraw.Draw(img_with_border) # 注意PIL的默认字体可能很小。在实际项目中你可能需要指定一个.ttf字体文件。 # font ImageFont.truetype(arial.ttf, 16) font ImageFont.load_default() text_bbox draw.textbbox((0,0), label_text, fontfont) text_width text_bbox[2] - text_bbox[0] text_position ((img_with_border.width - text_width) // 2, qr_img.height 10) draw.text(text_position, label_text, fillfill_color, fontfont) qr_img img_with_border except Exception as e: print(f警告添加标签失败 - {e}) # 5. 保存图片 qr_img.save(output_file) print(f✅ 二维码已成功保存至: {os.path.abspath(output_file)}) print(f 文件格式: {os.path.splitext(output_file)[1]}) print(f 图片尺寸: {qr_img.size[0]}x{qr_img.size[1]} 像素) def main(): parser argparse.ArgumentParser(description文本二维码生成器) parser.add_argument(text, help要编码为二维码的文本内容) parser.add_argument(-o, --output, defaultqrcode_output.png, help输出图片文件名 (默认: qrcode_output.png)) parser.add_argument(-v, --version, typeint, defaultNone, help二维码版本 (1-40)默认None自动确定) parser.add_argument(-e, --error_correction, choices[L,M,Q,H], defaultM, help纠错等级 L(7%%)/M(15%%)/Q(25%%)/H(30%%) (默认: M)) parser.add_argument(-s, --box_size, typeint, default10, help每个模块的像素大小 (默认: 10)) parser.add_argument(-b, --border, typeint, default4, help二维码边距 (模块数) (默认: 4)) parser.add_argument(-f, --fill_color, defaultblack, help二维码点颜色 (默认: black)) parser.add_argument(-bg, --back_color, defaultwhite, help背景颜色 (默认: white)) parser.add_argument(-l, --logo, help要嵌入的Logo图片路径) parser.add_argument(--label, help在二维码下方添加的标签文字) args parser.parse_args() # 检查输出目录是否存在不存在则创建 output_dir os.path.dirname(args.output) or . if output_dir and not os.path.exists(output_dir): os.makedirs(output_dir) # 调用核心函数 create_qr_code( dataargs.text, output_fileargs.output, versionargs.version, error_correctionargs.error_correction, box_sizeargs.box_size, borderargs.border, fill_colorargs.fill_color, back_colorargs.back_color, logoargs.logo, labelargs.label, ) if __name__ __main__: main()4.2 使用示例与运行验证将上述代码保存为qr_generator.py。下面演示几种不同的使用方式1. 基础生成# 生成一个包含网址的二维码 python qr_generator.py https://blog.csdn.net/your_profile -o output/csdn_qr.png2. 自定义样式大尺寸、彩色# 生成一个大尺寸、蓝底黄点的二维码 python qr_generator.py 会议室预约码A101-2023 -o meeting_qr.jpg -s 15 -f #FFD700 -bg #1E3A8A3. 高容错并添加Logo# 为产品生成带Logo和高容错的二维码 python qr_generator.py SN:PROD-2023-8876 -o product_qr.png -e H -l ./assets/company_logo.png --label 扫描验证真伪4. 生成纯文本信息二维码适用于STM32等嵌入式设备显示# 生成一个包含设备状态信息的二维码用于嵌入式屏幕显示 python qr_generator.py DeviceID:STM32F407;Temp:25.6C;Humidity:60%;Status:OK -o device_status_qr.png -s 8 -b 2这个例子生成的二维码信息密度高、尺寸小非常适合在分辨率有限的嵌入式显示屏如OLED上显示。运行命令后工具会打印生成日志并在指定路径输出二维码图片。你可以用手机扫码软件如微信、支付宝进行测试验证编码内容是否正确。5. 常见问题与排查思路在实际使用中你可能会遇到一些问题。下面列出一些典型问题及其解决方法。问题现象可能原因排查与解决思路生成的二维码无法被扫描识别1. 边距(border)设置过小如0。2. 图片尺寸太小模块(box_size)小于3像素。3. 颜色对比度太低如浅灰背景深灰点。4. 数据量超出所选版本容量。1.确保border至少为4库默认值。2. 增大box_size例如10或更大。3. 使用高对比度颜色组合黑白最稳妥。4. 不要指定过小的version或使用fitTrue让库自动选择版本。添加Logo后二维码无法识别1. Logo过大遮挡了过多关键数据定位图案、格式信息。2. 未使用高纠错等级。1.控制Logo大小不超过二维码区域的20%-25%。代码中我们使用了qr_width // 5即20%。2.添加Logo时务必使用error_correctionH最高容错。程序报错ModuleNotFoundError: No module named PILPillow库未正确安装。1. 确认虚拟环境已激活。2. 重新安装pip install qrcode[pil]。3. 或单独安装pip install Pillow。生成的图片模糊或有锯齿1.box_size太小然后图片被强制放大显示。2. 保存为JPG等有损格式。1. 直接设置更大的box_size来生成大图而不是生成小图再放大。2. 对于需要高清晰度的场合如印刷优先使用PNG格式。编码中文或特殊字符时出错字符串编码问题。1. 确保Python脚本文件本身以UTF-8编码保存。2. 在命令行传递中文时注意终端编码。在代码内部使用Unicode字符串。qrcode库内部会处理编码。数据太长二维码变得非常密集数据量超出了低版本容量库自动使用了高版本如version 40。1. 这是正常现象。高版本二维码模块更小更密。2. 如果希望物理尺寸不变可以尝试压缩数据如使用短链接、缩写。3. 考虑将数据拆分生成多个二维码。通用排查步骤简化测试先用最简单的黑白、默认参数生成一个纯文本二维码看是否能被识别。排除样式干扰。检查参数核对border、box_size、error_correction等关键参数是否在合理范围。验证数据检查要编码的文本内容是否包含不可见字符或格式问题。可以尝试编码一个简单的“Hello World”来对比。更换扫码器有时某些扫码APP对非标准二维码如彩色、带Logo支持不佳换一个专业的扫码工具如手机相册自带、Google Lens试试。6. 最佳实践与工程化建议将二维码生成功能集成到实际项目中时遵循一些最佳实践可以提升代码的健壮性、性能和可维护性。6.1 性能优化批量生成如果需要生成大量二维码避免在循环中反复创建和销毁QRCode对象。可以考虑复用部分配置但注意add_data后需要调用clear()或创建新对象。尺寸与格式选择网络传输/网页显示使用PNG格式无损box_size可以小一些如6-8以减小文件体积。打印/高精度显示使用PNG或TIFF格式box_size根据打印DPI计算例如300 DPI打印希望每个模块0.25mm则box_size int(300 * 0.25 / 25.4) ≈ 3但通常需要更大。嵌入式设备显示如STM32驱动的LCD/OLED屏box_size通常设为1或2并关闭边距(border0或1)以节省像素空间但需确保扫码软件能识别。6.2 错误处理与日志输入验证对输入文本的长度做检查。虽然库会自动选择版本但过长的数据如超过几千字符会导致版本40都放不下应提前提示用户。文件操作在保存图片前检查输出目录的写入权限。使用try...except包裹文件保存操作。资源清理如果处理大量图片注意PIL Image对象的显式关闭img.close()或使用with语句避免内存泄漏。6.3 安全性考虑内容安全二维码可以编码任何文本包括恶意URL或脚本。如果你的工具面向用户开放应考虑对输入内容进行安全过滤或警告。Logo来源验证用户上传的Logo文件格式和大小防止恶意文件攻击。6.4 集成到Web服务或GUI应用Web后端Flask/Django可以将生成逻辑封装成函数或类。在视图函数中接收文本参数生成二维码图片然后通过BytesIO将图片数据存入内存直接以HTTP响应返回避免写入磁盘。# Flask示例片段 from flask import send_file import io app.route(/generate_qr) def generate_qr(): text request.args.get(text, ) img_io io.BytesIO() # ... 调用create_qr_code生成图片 ... qr_img.save(img_io, PNG) img_io.seek(0) return send_file(img_io, mimetypeimage/png)GUI应用Tkinter/PyQt生成PIL.Image对象后可以转换为PhotoImage或QPixmap直接显示在界面上。与STM32等嵌入式设备配合这是相关热搜词中的一个重要场景。通常流程是PC端或服务器生成二维码图片然后通过图像处理算法或使用专用库将二维码的二进制矩阵提取出来转换为C语言数组或直接转换为黑白像素流通过串口、USB或网络发送给STM32STM32再控制LCD屏进行绘制。这涉及到图像二值化、取模等步骤已超出本文范围但核心的二维码生成部分正是本文所讲内容。6.5 代码可维护性配置化将常用的参数组合如“小尺寸打印配置”、“Web显示配置”、“带Logo的企业配置”提取为配置字典或配置文件。单元测试为核心的create_qr_code函数编写单元测试测试不同参数组合下是否能成功生成文件以及生成的文件是否可被标准库解码qrcode库也提供了简单的解码功能可用于测试验证。通过遵循这些实践你的二维码生成工具就能从一个小脚本稳步成长为一个可靠、易用的项目模块。无论是集成到自动化流程、Web应用还是为物联网设备提供数据可视化接口它都能胜任。