我这两年帮朋友处理过不少商品物料整理的事最常被问的一句话就是“能不能直接给我生成一批码”。所谓“一句代码生成二维码一句代码生成条形码批量生成二维码和条形码”听起来像是标题党但等我完整跑了一遍流程后发现这还真不是夸大其词。背后用的就是Python里两个很成熟的库核心生成调用真的就一行加上循环逻辑就能批量出图扫码枪实测也能稳定识别。这篇文章我会从零开始把步骤拆开讲包括库怎么装、参数怎么调、批量脚本怎么写、打印排版怎么做以及我实际踩过的坑。适合要做仓库贴标、产品包装码、ERP辅助小工具或者纯粹想省掉在线生成器手动下载麻烦的读者。1. 项目概述与需求拆解1.1 这个需求到底要解决什么“一句代码生成二维码一句代码生成条形码”拆开看其实是三个层层递进的需求。第一层是单张二维码生成。最典型的场景是我想把商品详情链接、产品序列号或者一段文本变成一张能扫的图片直接贴在包装或者文档上。以前大家习惯打开在线二维码生成网站填数据、选尺寸、下载图片单张还好量一多光是重复操作就够烦的。第二层是单张条形码生成。条形码和二维码的使用场景不太一样二维码适合存一段较长信息比如网址、JSON文本条形码适合存短编码比如SKU、批次号、13位商品编码而且要在极窄的空间里让扫码枪快速识别。很多朋友分不清这两者实际上它们是两套完全不同的编码规则库的选择也不同。第三层是批量生成。当你手上有几百上千条商品数据每条都要生成“二维码条形码”两张图这个时候核心需求已经不再是“怎么生成一张”而是“怎么用一张数据表驱动所有图片输出”并且文件命名要规范、错误要能定位、最终还要方便打印贴标。1.2 方案选型与“一句代码”的秘密我选择本地脚本方案而不是在线工具原因很直接在线工具有三个致命问题——数据敏感商品编码和内部链接不想经过第三方服务器效率低一张张手动下载几百条能弄一整天参数不可控在线工具导出的图片尺寸、留白、容错率未必符合你的打印场景。本地脚本我选了Python不是因为它最强而是因为它生态最省心。二维码用qrcode库条形码用python-barcode库两者都封装好了完整的编码算法你不需要关心纠错算法怎么算、条的宽窄怎么排只需要用高层API传数据和参数。为什么能做到“一句代码”因为这些库的设计者已经替你处理了最复杂的那部分。二维码的编码、掩码、纠错条形码的宽度映射、校验位计算这些都是已经解决过无数遍的通用问题被封装成了一个make()、一个get()。这就像你不需要懂内燃机原理也能开车一样工具把人从底层细节里解放了出来。真正需要你花时间的是理解几个影响成图质量的参数以及批量的流程设计。2. 环境准备与核心工具安装2.1 Python环境与必要的编辑器如果你的电脑上还没有Python环境直接去Python官网下载安装包安装的时候务必勾选“Add Python to PATH”否则后面在命令行里敲pip会提示找不到命令。这个细节我见过太多次很多人卡在环境变量上还没开始就放弃了。编辑器方面新手直接用IDLE或任何能写.py文件的文本编辑器都行。我更推荐你装一个支持代码高亮的编辑器写起来不容易出错。不过这个项目比较简单哪怕用系统自带的记事本也能完成只是没有高亮和自动补全代码一长就容易看漏括号。2.2 安装两个核心库打开命令行工具Windows下是CMD或PowerShellmacOS/Linux下是终端执行下面的命令pip install qrcode[pil] python-barcode[pil]这里的[pil]很关键。它代表安装时连同Pillow图像库一起装上。二维码和条形码要输出成PNG图片底层必须靠Pillow来编码图像如果不加[pil]qrcode就只能输出文本形式的二维码python-barcode则默认只能输出SVG矢量格式没法直接得到位图PNG。安装完成后验证一下命令行里输入python -c import qrcode, barcode; print(ok)看到输出ok就说明环境没问题。如果pip提示版本太低可以先执行pip install --upgrade pip再装一次如果遇到权限问题在Linux/macOS下可以加--user参数。2.3 可选处理Excel数据需要的库如果批量数据存的是CSV文件Python自带的csv模块就够用不需要额外装东西。如果数据在xlsx文件里建议安装支持Excel读取的库pip install openpyxl pandaspandas是数据分析常用的库读写Excel非常方便openpyxl负责解析xlsx文件。后面的批量示例我尽量用CSV演示这样对零基础读者更友好不需要装额外的重量级依赖。CSV可以用Excel直接另存为生成本质上仍然是你熟悉的表格。3. 一句代码生成二维码3.1 最小化调用体验先把最纯粹的一行代码给你看看确认环境后新建一个make_qr.py文件写入import qrcode qrcode.make(https://example.com/product/1001).save(qr_1001.png)运行这个文件你会发现在同目录下多了一个qr_1001.png这就是一张可以直接用手机扫出来的二维码图片。严格来说这是两个语句第一行导入库第二行生成并保存。标题里的“一句代码”指的其实是核心生成动作只有一句——make()生成二维码对象随后直接调用.save()落盘。qrcode的make()方法返回的是一个Pillow图像对象所以它自然继承了Pillow的保存能力一行串起来非常顺。如果你想再较真一点用下面这种写法也能把两个语句压缩成一行__import__(qrcode).make(https://example.com/product/1001).save(qr_1001.png)但这种写法可读性太差不推荐在日常代码里用。理解“核心调用只有一句话”这个思路就够了。还有一点要注意save()方法里的文件名一定要带.png后缀否则保存出来的是没有扩展名的文件很多看图软件打不开。3.2 用参数控制尺寸、容错率和颜色上面的一行代码用的是默认参数适合快速验证。实际项目里二维码的用途五花八门对应需要调节的参数也不一样。qrcode库提供了QRCode类允许你显式控制各种参数import qrcode qr qrcode.QRCode( version3, error_correctionqrcode.constants.ERROR_CORRECT_H, box_size10, border4, ) qr.add_data(https://example.com/product/1001) qr.make(fitTrue) img qr.make_image(fill_colorblack, back_colorwhite) img.save(qr_1001_custom.png)先解释几个参数的含义version二维码的版本取值范围1到40。版本1是21×21个模块之后每增加一版边长增加4个模块。版本越高级能容纳的数据越多。手动指定version可以保证同批次二维码尺寸完全一致比如统一用version 3的29×29模块。error_correction容错率。L约可恢复7%的损坏M约15%Q约25%H约30%。如果二维码要印在包装盒上可能被折痕、反光、油墨污渍干扰建议至少选M重要场景选H。容错率越高能存放的数据量越小这需要平衡。box_size每个模块的像素大小。box_size10意味着每个黑白小方块是10像素×10像素整体尺寸大约是290×290像素版本3情况下。打印输出建议不要小于8否则印刷后可能过密。border二维码四周的留白宽度单位是模块数。标准规范要求至少4个模块也就是border4这样扫码设备更容易定位。留白不足是导致扫码失败的常见原因之一。fill_color和back_color控制了前景色和背景色。只能使用深色前景、浅色背景这是二维码识别的基本要求。我曾经见过有人把二维码做成了白底白块、黑底黑块的反色样式结果扫码枪完全不认。也不要为了好看把背景换成复杂图案每一步额外的图形干扰都是在降低识别成功率。下面是一个速查表方便以后直接套用参数作用我的推荐version控制模块尺寸规格数据少时自动批量统一则固定error_correction纠错能力包装印刷选H屏幕显示选Mbox_size模块像素大小打印场景不低于8border安静区宽度不低于4宁多勿少fill_color/back_color前景/背景色黑配白最稳3.3 二维码里的中文和长文本qrcode库默认支持UTF-8编码所以你往里面放中文文本、带中文参数的URL都没问题。比如链接是https://example.com/?name测试商品直接丢进add_data()就能正常生成。手机扫码后浏览器会自动解析中文参数大多数情况下不会出现乱码。但是有一个坑如果你要在二维码里存的信息是经过URL编码的比如%E6%B5%8B%E8%AF%95这种形式生成出来的码扫出来就是那一串百分号字符而不是中文。这种情况下最好解码后再放入二维码或者保持原样告知使用方。实际项目中商品详情链接通常已经是处理好的短链接不太会遇到这个问题。长文本方面version40的理论容量可以容纳约3000个字符数字模式更多但信息越长、密度越高对打印和识别的要求也越高。我的经验是当内容超过500个字符时优先考虑缩短内容比如用短链接而不是硬塞进二维码。二维码不是文本存储工具它更适合放一个“入口”。4. 一句代码生成条形码4.1 最小化调用体验条形码生成用python-barcode库。新建make_barcode.pyimport barcode from barcode.writer import ImageWriter barcode.get(code128, SKU-2024-001, writerImageWriter()).save(barcode_sku)运行后在同目录下会生成barcode_sku.png这是一张Code128格式的条形码。这里和二维码有一个明显的差异生成条形码必须指定一种编码标准也就是第一个参数。因为条形码不是通用的“一段数据”而是按不同规则组织的符号体系。code128是最通用的选择它支持全部ASCII字符长度灵活密度也不错适合企业内部SKU、批次号。零售商品上常见的EAN-13也是条形码的一种但规则不同下面单独说。writerImageWriter()指的是用Pillow图像写入器输出PNG位图。如果不指定这个参数默认会输出SVG矢量图。SVG的好处是无限缩放不失真适合印刷到大型包装上但日常使用中PNG更通用绝大部分贴标软件和图片查看器都能直接处理。4.2 条形码格式怎么选Code128还是EAN13条形码格式不能凭感觉选选错了轻则扫码枪读不出来重则不符合渠道要求。下面这张表整理了几种常见格式的适用场景格式支持字符典型长度适用场景Code128全ASCII字符灵活企业内部SKU、物流运单、批次号Code39数字、大写字母、几个符号灵活但较宽工业标签、资产管理EAN-1313位数字固定13位零售商品条码超市结算EAN-88位数字固定8位小包装零售商品UPC-A12位数字固定12位北美零售商品如果你生成的条码要进商超系统必须用EAN-13而且这个13位数字要按分配规则申请不能自己编一个。如果只是在公司内部流转、仓库管理、发货贴标用Code128是最省心的因为它支持字母数字混合长度也不受限。python-barcode在生成EAN-13时有校验位逻辑你可以只传入前12位数字库会自动计算第13位校验码。比如barcode.get(ean13, 690123456789, writerImageWriter()).save(ean_demo)这里如果传的字符串长度不是12位或者含有非数字字符程序会直接报错。如果你硬传13位但最后一位和计算出的校验码不一致库也会提醒校验失败。这是很多朋友第一次用会感到困惑的地方——明明我给了完整13位怎么还报错。原因就是EAN-13的第13位不是一个普通数字而是由前12位算出来的校验位。4.3 控制条码高度、字体与静区条形码能不能被快速识别不仅取决于内容格式还取决于打印后的物理尺寸和留白。python-barcode在保存时可以通过options字典控制这些import barcode from barcode.writer import ImageWriter options { module_width: 0.3, module_height: 12.0, font_size: 10, text_distance: 5.0, quiet_zone: 6.5, background: white, foreground: black, } barcode.get(code128, SKU-2024-001, writerImageWriter()).save(barcode_sku_fmt, options)各参数含义module_width最窄条的宽度单位是毫米。太窄会导致扫描距离变短太宽又会浪费纸张。普通标签我一般用0.3mm左右。module_height条形码垂直方向的高度单位毫米。太矮的条码扫码枪很难对准建议不低于10mm。font_size条码下方人类可读的字符大小。text_distance字符和条形码之间的间距。quiet_zone左右两侧的静区宽度单位毫米。静区是扫描设备识别条码起止位置必需的空白区域过小会直接导致扫描失败。标准静区建议至少是10倍最窄条宽6.5mm是一个比较稳妥的默认值。还要提醒一个容易忽略的点save(barcode_sku_fmt)不要自己手动加.png后缀。python-barcode的保存逻辑会自动补上writer对应的扩展名你写成save(barcode_sku_fmt.png)反而会生成一个barcode_sku_fmt.png.png文件。这个我见过不止一次尤其在和二维码的写法混着用时特别容易踩。5. 批量生成二维码和条形码5.1 准备数据源批量生成的前提是有一份规范的数据表。我习惯用CSV文件因为它轻量、通用、Excel也能直接编辑。创建一个items.csv内容大致是sku,text SKU-001,https://example.com/product/1001 SKU-002,https://example.com/product/1002 SKU-003,ABC-2024-0033 SKU-004,https://example.com/?keyword%E6%B5%8B%E8%AF%95字段设计很简单sku作为输出文件的命名依据text作为要编码的实际内容。同一个text可以同时用于二维码和条形码吗?这取决于内容。如果是纯ASCII短文本两个都能生成如果内容是带中文的长链接条形码的Code128不支持中文会直接报错。所以数据表设计时分两列更稳妥sku,qr_content,bar_content SKU-001,https://example.com/product/1001,SKU-001 SKU-002,https://example.com/product/1002,SKU-002这样二维码内容可以随意放长链接条形码内容用短编码两者互不干扰。这个看似微小的设计在批量场景下能避免大量报错。5.2 批量循环生成与文件命名主流程其实就是把单张生成的代码包进一个循环里。下面是一个比较完整的批量脚本import os import csv import qrcode import barcode from barcode.writer import ImageWriter os.makedirs(output_qr, exist_okTrue) os.makedirs(output_barcode, exist_okTrue) with open(items.csv, r, encodingutf-8-sig) as f: reader csv.DictReader(f) for row in reader: sku row[sku].strip() qr_content row[qr_content].strip() bar_content row[bar_content].strip() qrcode.make(qr_content).save(foutput_qr/{sku}.png) barcode.get(code128, bar_content, writerImageWriter()).save( foutput_barcode/{sku}, options{ module_width: 0.3, module_height: 12.0, quiet_zone: 6.5, } ) print(f已生成: {sku})这段代码里有几个细节值得说。encodingutf-8-sig是为了兼容Excel另存为CSV时自动添加的BOM头。如果用不带的编码去读第一行第一列会出现一个不可见的\ufeff字符导致第一个SKU文件名变成\ufeffSKU-001.png看起来正常但处理起来很闹心。os.makedirs(..., exist_okTrue)会自动创建输出目录目录已存在时不会报错。这个细节能省掉你反复手动新建文件夹的麻烦。barcode.get(...).save()的保存路径同样不带.pngpython-barcode会自己加扩展名。如果bar_content里碰巧有中文这一步会抛出异常后面的代码块会讲怎么捕获。5.3 批量导出到A4打印拼版批量生成一堆PNG之后下一步通常是打印贴标。如果你直接用系统图片打印功能每张图占一页浪费纸张而且标签大小难控制。更常见的做法是把多个码拼到一张A4纸上。用Pillow做一个简单的拼版功能。以300dpi的A4画布为例尺寸是2480×3508像素。我想在一张A4上放3列×5行共15张标签from PIL import Image import os A4_W, A4_H 2480, 3508 COLS, ROWS 3, 5 MARGIN 80 GAP 30 qr_dir output_qr files sorted(os.listdir(qr_dir)) page Image.new(RGB, (A4_W, A4_H), white) cell_w (A4_W - 2 * MARGIN - (COLS - 1) * GAP) / COLS cell_h (A4_H - 2 * MARGIN - (ROWS - 1) * GAP) / ROWS for idx, filename in enumerate(files): if idx COLS * ROWS: break img Image.open(os.path.join(qr_dir, filename)) # 等比缩放并居中 img.thumbnail((int(cell_w - 20), int(cell_h - 20)), Image.LANCZOS) col idx % COLS row idx // COLS x MARGIN col * (cell_w GAP) (cell_w - img.width) // 2 y MARGIN row * (cell_h GAP) (cell_h - img.height) // 2 page.paste(img, (int(x), int(y))) page.save(qrcode_a4_page1.png)这段代码的本质是“计算格子坐标把图片贴到画布对应位置”。Image.thumbnail()会按比例缩小图片避免长宽变形paste前计算居中偏移保证每张码在格子中间不歪斜。这里有一个要留意的点如果生成的二维码是正方形条形码是宽扁矩形两者拼在同一个格子里时构图差异很大。条形码是用高和宽比来保证可识别性的如果被thumbnail压缩得过小可能会影响扫描所以条形码拼版时建议单独处理给更宽的格子或者直接把两个码画在一张标签图里。6. 常见问题与排查技巧实录6.1 二维码扫不出来的三种情况第一种是尺寸问题。二维码在屏幕上显示没问题一旦打印成实物就扫不出来多半是模块密度过高或打印尺寸过小。比如box_size3的二维码放在手机上看很清晰但打到6号字大小的位置就是一团噪点。排查方法很简单测距手机离二维码20到30厘米扫一下如果对焦都困难把box_size调大或者打印时把物理尺寸放大。第二种是容错率不够。二维码被遮住一部分时低于那个遮罩比例就会失效。比如选了L级容错遮罩只要超过约7%就直接扫描失败。经常遇到的情况是包装上有塑封反光、折痕压过二维码一角。保守方案是统一用H级容错代价是信息容量变小但普通链接通常不受影响。第三种是反色或深色背景。前面提过了二维码只能深内容浅背景。有些人为了设计感把二维码做成深灰底白色块或者把背景做成深蓝这些都会造成识别率断崖式下降。改回黑块白底是最稳妥的没有之一。6.2 条形码识别失败的原因条形码的问题比二维码更多出现在格式和静区上。我排查过不少案例最后归结为五大类现象原因解决办法扫不出来但有条码图像静区不够加大quiet_zone到6.5mm以上扫出来数字不对校验位错误让库自动计算第13位或者13位都核对条码太矮扫不到module_height太小增高到10mm以上打印模糊、条空粘连打印机分辨率不足降低module_width或换200dpi以上打印机含中文导致报错Code128不支持中文中文内容改用二维码条形码用英文/数字编码条形码的“条”和“空”宽度比例是编码规则决定的激光扫描头需要越过黑条和白空来解析宽度。如果打印时墨水洇开黑条变宽白空变窄解析就会失误。所以打印条形码时不要用普通A4纸加墨水喷墨打印机热敏标签机或激光打印机是更靠谱的选择。6.3 中文内容不能直接生成条形码这个坑在批量脚本里尤其致命。Code128虽然支持全部ASCII字符但中文不在其列。如果bar_content是“测试商品01”python-barcode在编码时会对中文字符报编码错误。解决方案有三个一是把中文内容转去生成二维码条形码只放SKU、拼音缩写或数字编号二是自行将中文转成拼音或ASCII码三是改用支持中文的条码标准比如QR Code或者Data Matrix但严格来说它们已经不是传统意义上的条形码了。批量脚本里我会在循环体内单独捕获条形码生成异常不让一个失败的数据把整个流程打断try: barcode.get(code128, bar_content, writerImageWriter()).save(...) except Exception: print(fSKU {sku} 条形码生成失败内容可能含中文)配合一个错误记录文件几百条数据跑完后直接看日志就能定位哪些SKU的数据源要调整不用盯着控制台翻。6.4 几千条数据很慢怎么办批量生成几千条二维码和条形码单线程跑一般也就几分钟瓶颈主要出在PNG编码和文件写入上。多数场景不需要优化但如果数据量到了几万条就要考虑两点。第一输出格式改用SVG。SVG本质是文本生成速度比位图快而且矢量图打印质量更高。第二用多线程并发。Python的concurrent.futures.ThreadPoolExecutor可以把生成任务分发到多个线程IO密集型的图像写入能明显提速。不过要小心线程数不要超过CPU核心数的两倍否则反而会因为上下文切换变慢。实用建议是批量脚本先抽5条样本跑一遍确认图片尺寸、清晰度、文件命名都符合预期再全量跑。全量跑完后再随机抽3到5张用手机和扫码枪实测。生成环节省下来的时间远没有返工浪费时间来得痛。6.5 中文文件名和非法字符问题文件命名时sku列如果有/、:、*、?这类系统非法字符save()时会直接报错。Windows下尤其严格。解决办法是生成文件名前先做一次清洗import re def safe_filename(sku): return re.sub(r[\\/:*?|], _, sku)这个方法会把所有不适合出现在文件名里的字符替换成下划线。这个细节看着小但在真实物料数据里非常常见特别是在SKU设计不规范的老系统里脏数据一堆。7. 这个能力还能往哪扩展如果你已经顺利跑通了批量生成这个能力的扩展空间其实很大。我自己用着比较顺手的方向是给内部工具加一个简单的Web接口用Flask或FastAPI封装一个路由前端输入数据后端动态生成二维码图片返回这样业务同事就不用碰Python代码直接在浏览器页面里操作。本质还是那个库只是把“一句代码”包在了接口里。另外如果你要给非技术同事使用可以用PyInstaller把脚本打包成一个exe可执行文件。打包前把脚本改造成可以接收命令行参数或直接读取固定位置CSV的版本双击即用不用装Python环境。这个实践对团队内的工具交付很有价值我之前把一个物料码批量工具打给仓库同事用极大地减少了中间传话成本。最后分享一个我个人的小习惯不管工具多简单我总会先花一分钟确认“这个码扫出来的是预期内容”。手机扫一下二维码看链接对不对扫码枪试一下条形码看数字对不对再开始批量。批量脚本再快也不如这种马上就能发现问题的验证来得便宜。造码这件事技术难点其实早就被开源库解决了剩下的功夫都花在参数、规范和数据治理上把这些想清楚你的码才能真正好用。
我这两年帮朋友处理过不少商品物料整理的事最常被问的一句话就是“能不能直接给我生成一批码”。所谓“一句代码生成二维码一句代码生成条形码批量生成二维码和条形码”听起来像是标题党但等我完整跑了一遍流程后发现这还真不是夸大其词。背后用的就是Python里两个很成熟的库核心生成调用真的就一行加上循环逻辑就能批量出图扫码枪实测也能稳定识别。这篇文章我会从零开始把步骤拆开讲包括库怎么装、参数怎么调、批量脚本怎么写、打印排版怎么做以及我实际踩过的坑。适合要做仓库贴标、产品包装码、ERP辅助小工具或者纯粹想省掉在线生成器手动下载麻烦的读者。1. 项目概述与需求拆解1.1 这个需求到底要解决什么“一句代码生成二维码一句代码生成条形码”拆开看其实是三个层层递进的需求。第一层是单张二维码生成。最典型的场景是我想把商品详情链接、产品序列号或者一段文本变成一张能扫的图片直接贴在包装或者文档上。以前大家习惯打开在线二维码生成网站填数据、选尺寸、下载图片单张还好量一多光是重复操作就够烦的。第二层是单张条形码生成。条形码和二维码的使用场景不太一样二维码适合存一段较长信息比如网址、JSON文本条形码适合存短编码比如SKU、批次号、13位商品编码而且要在极窄的空间里让扫码枪快速识别。很多朋友分不清这两者实际上它们是两套完全不同的编码规则库的选择也不同。第三层是批量生成。当你手上有几百上千条商品数据每条都要生成“二维码条形码”两张图这个时候核心需求已经不再是“怎么生成一张”而是“怎么用一张数据表驱动所有图片输出”并且文件命名要规范、错误要能定位、最终还要方便打印贴标。1.2 方案选型与“一句代码”的秘密我选择本地脚本方案而不是在线工具原因很直接在线工具有三个致命问题——数据敏感商品编码和内部链接不想经过第三方服务器效率低一张张手动下载几百条能弄一整天参数不可控在线工具导出的图片尺寸、留白、容错率未必符合你的打印场景。本地脚本我选了Python不是因为它最强而是因为它生态最省心。二维码用qrcode库条形码用python-barcode库两者都封装好了完整的编码算法你不需要关心纠错算法怎么算、条的宽窄怎么排只需要用高层API传数据和参数。为什么能做到“一句代码”因为这些库的设计者已经替你处理了最复杂的那部分。二维码的编码、掩码、纠错条形码的宽度映射、校验位计算这些都是已经解决过无数遍的通用问题被封装成了一个make()、一个get()。这就像你不需要懂内燃机原理也能开车一样工具把人从底层细节里解放了出来。真正需要你花时间的是理解几个影响成图质量的参数以及批量的流程设计。2. 环境准备与核心工具安装2.1 Python环境与必要的编辑器如果你的电脑上还没有Python环境直接去Python官网下载安装包安装的时候务必勾选“Add Python to PATH”否则后面在命令行里敲pip会提示找不到命令。这个细节我见过太多次很多人卡在环境变量上还没开始就放弃了。编辑器方面新手直接用IDLE或任何能写.py文件的文本编辑器都行。我更推荐你装一个支持代码高亮的编辑器写起来不容易出错。不过这个项目比较简单哪怕用系统自带的记事本也能完成只是没有高亮和自动补全代码一长就容易看漏括号。2.2 安装两个核心库打开命令行工具Windows下是CMD或PowerShellmacOS/Linux下是终端执行下面的命令pip install qrcode[pil] python-barcode[pil]这里的[pil]很关键。它代表安装时连同Pillow图像库一起装上。二维码和条形码要输出成PNG图片底层必须靠Pillow来编码图像如果不加[pil]qrcode就只能输出文本形式的二维码python-barcode则默认只能输出SVG矢量格式没法直接得到位图PNG。安装完成后验证一下命令行里输入python -c import qrcode, barcode; print(ok)看到输出ok就说明环境没问题。如果pip提示版本太低可以先执行pip install --upgrade pip再装一次如果遇到权限问题在Linux/macOS下可以加--user参数。2.3 可选处理Excel数据需要的库如果批量数据存的是CSV文件Python自带的csv模块就够用不需要额外装东西。如果数据在xlsx文件里建议安装支持Excel读取的库pip install openpyxl pandaspandas是数据分析常用的库读写Excel非常方便openpyxl负责解析xlsx文件。后面的批量示例我尽量用CSV演示这样对零基础读者更友好不需要装额外的重量级依赖。CSV可以用Excel直接另存为生成本质上仍然是你熟悉的表格。3. 一句代码生成二维码3.1 最小化调用体验先把最纯粹的一行代码给你看看确认环境后新建一个make_qr.py文件写入import qrcode qrcode.make(https://example.com/product/1001).save(qr_1001.png)运行这个文件你会发现在同目录下多了一个qr_1001.png这就是一张可以直接用手机扫出来的二维码图片。严格来说这是两个语句第一行导入库第二行生成并保存。标题里的“一句代码”指的其实是核心生成动作只有一句——make()生成二维码对象随后直接调用.save()落盘。qrcode的make()方法返回的是一个Pillow图像对象所以它自然继承了Pillow的保存能力一行串起来非常顺。如果你想再较真一点用下面这种写法也能把两个语句压缩成一行__import__(qrcode).make(https://example.com/product/1001).save(qr_1001.png)但这种写法可读性太差不推荐在日常代码里用。理解“核心调用只有一句话”这个思路就够了。还有一点要注意save()方法里的文件名一定要带.png后缀否则保存出来的是没有扩展名的文件很多看图软件打不开。3.2 用参数控制尺寸、容错率和颜色上面的一行代码用的是默认参数适合快速验证。实际项目里二维码的用途五花八门对应需要调节的参数也不一样。qrcode库提供了QRCode类允许你显式控制各种参数import qrcode qr qrcode.QRCode( version3, error_correctionqrcode.constants.ERROR_CORRECT_H, box_size10, border4, ) qr.add_data(https://example.com/product/1001) qr.make(fitTrue) img qr.make_image(fill_colorblack, back_colorwhite) img.save(qr_1001_custom.png)先解释几个参数的含义version二维码的版本取值范围1到40。版本1是21×21个模块之后每增加一版边长增加4个模块。版本越高级能容纳的数据越多。手动指定version可以保证同批次二维码尺寸完全一致比如统一用version 3的29×29模块。error_correction容错率。L约可恢复7%的损坏M约15%Q约25%H约30%。如果二维码要印在包装盒上可能被折痕、反光、油墨污渍干扰建议至少选M重要场景选H。容错率越高能存放的数据量越小这需要平衡。box_size每个模块的像素大小。box_size10意味着每个黑白小方块是10像素×10像素整体尺寸大约是290×290像素版本3情况下。打印输出建议不要小于8否则印刷后可能过密。border二维码四周的留白宽度单位是模块数。标准规范要求至少4个模块也就是border4这样扫码设备更容易定位。留白不足是导致扫码失败的常见原因之一。fill_color和back_color控制了前景色和背景色。只能使用深色前景、浅色背景这是二维码识别的基本要求。我曾经见过有人把二维码做成了白底白块、黑底黑块的反色样式结果扫码枪完全不认。也不要为了好看把背景换成复杂图案每一步额外的图形干扰都是在降低识别成功率。下面是一个速查表方便以后直接套用参数作用我的推荐version控制模块尺寸规格数据少时自动批量统一则固定error_correction纠错能力包装印刷选H屏幕显示选Mbox_size模块像素大小打印场景不低于8border安静区宽度不低于4宁多勿少fill_color/back_color前景/背景色黑配白最稳3.3 二维码里的中文和长文本qrcode库默认支持UTF-8编码所以你往里面放中文文本、带中文参数的URL都没问题。比如链接是https://example.com/?name测试商品直接丢进add_data()就能正常生成。手机扫码后浏览器会自动解析中文参数大多数情况下不会出现乱码。但是有一个坑如果你要在二维码里存的信息是经过URL编码的比如%E6%B5%8B%E8%AF%95这种形式生成出来的码扫出来就是那一串百分号字符而不是中文。这种情况下最好解码后再放入二维码或者保持原样告知使用方。实际项目中商品详情链接通常已经是处理好的短链接不太会遇到这个问题。长文本方面version40的理论容量可以容纳约3000个字符数字模式更多但信息越长、密度越高对打印和识别的要求也越高。我的经验是当内容超过500个字符时优先考虑缩短内容比如用短链接而不是硬塞进二维码。二维码不是文本存储工具它更适合放一个“入口”。4. 一句代码生成条形码4.1 最小化调用体验条形码生成用python-barcode库。新建make_barcode.pyimport barcode from barcode.writer import ImageWriter barcode.get(code128, SKU-2024-001, writerImageWriter()).save(barcode_sku)运行后在同目录下会生成barcode_sku.png这是一张Code128格式的条形码。这里和二维码有一个明显的差异生成条形码必须指定一种编码标准也就是第一个参数。因为条形码不是通用的“一段数据”而是按不同规则组织的符号体系。code128是最通用的选择它支持全部ASCII字符长度灵活密度也不错适合企业内部SKU、批次号。零售商品上常见的EAN-13也是条形码的一种但规则不同下面单独说。writerImageWriter()指的是用Pillow图像写入器输出PNG位图。如果不指定这个参数默认会输出SVG矢量图。SVG的好处是无限缩放不失真适合印刷到大型包装上但日常使用中PNG更通用绝大部分贴标软件和图片查看器都能直接处理。4.2 条形码格式怎么选Code128还是EAN13条形码格式不能凭感觉选选错了轻则扫码枪读不出来重则不符合渠道要求。下面这张表整理了几种常见格式的适用场景格式支持字符典型长度适用场景Code128全ASCII字符灵活企业内部SKU、物流运单、批次号Code39数字、大写字母、几个符号灵活但较宽工业标签、资产管理EAN-1313位数字固定13位零售商品条码超市结算EAN-88位数字固定8位小包装零售商品UPC-A12位数字固定12位北美零售商品如果你生成的条码要进商超系统必须用EAN-13而且这个13位数字要按分配规则申请不能自己编一个。如果只是在公司内部流转、仓库管理、发货贴标用Code128是最省心的因为它支持字母数字混合长度也不受限。python-barcode在生成EAN-13时有校验位逻辑你可以只传入前12位数字库会自动计算第13位校验码。比如barcode.get(ean13, 690123456789, writerImageWriter()).save(ean_demo)这里如果传的字符串长度不是12位或者含有非数字字符程序会直接报错。如果你硬传13位但最后一位和计算出的校验码不一致库也会提醒校验失败。这是很多朋友第一次用会感到困惑的地方——明明我给了完整13位怎么还报错。原因就是EAN-13的第13位不是一个普通数字而是由前12位算出来的校验位。4.3 控制条码高度、字体与静区条形码能不能被快速识别不仅取决于内容格式还取决于打印后的物理尺寸和留白。python-barcode在保存时可以通过options字典控制这些import barcode from barcode.writer import ImageWriter options { module_width: 0.3, module_height: 12.0, font_size: 10, text_distance: 5.0, quiet_zone: 6.5, background: white, foreground: black, } barcode.get(code128, SKU-2024-001, writerImageWriter()).save(barcode_sku_fmt, options)各参数含义module_width最窄条的宽度单位是毫米。太窄会导致扫描距离变短太宽又会浪费纸张。普通标签我一般用0.3mm左右。module_height条形码垂直方向的高度单位毫米。太矮的条码扫码枪很难对准建议不低于10mm。font_size条码下方人类可读的字符大小。text_distance字符和条形码之间的间距。quiet_zone左右两侧的静区宽度单位毫米。静区是扫描设备识别条码起止位置必需的空白区域过小会直接导致扫描失败。标准静区建议至少是10倍最窄条宽6.5mm是一个比较稳妥的默认值。还要提醒一个容易忽略的点save(barcode_sku_fmt)不要自己手动加.png后缀。python-barcode的保存逻辑会自动补上writer对应的扩展名你写成save(barcode_sku_fmt.png)反而会生成一个barcode_sku_fmt.png.png文件。这个我见过不止一次尤其在和二维码的写法混着用时特别容易踩。5. 批量生成二维码和条形码5.1 准备数据源批量生成的前提是有一份规范的数据表。我习惯用CSV文件因为它轻量、通用、Excel也能直接编辑。创建一个items.csv内容大致是sku,text SKU-001,https://example.com/product/1001 SKU-002,https://example.com/product/1002 SKU-003,ABC-2024-0033 SKU-004,https://example.com/?keyword%E6%B5%8B%E8%AF%95字段设计很简单sku作为输出文件的命名依据text作为要编码的实际内容。同一个text可以同时用于二维码和条形码吗?这取决于内容。如果是纯ASCII短文本两个都能生成如果内容是带中文的长链接条形码的Code128不支持中文会直接报错。所以数据表设计时分两列更稳妥sku,qr_content,bar_content SKU-001,https://example.com/product/1001,SKU-001 SKU-002,https://example.com/product/1002,SKU-002这样二维码内容可以随意放长链接条形码内容用短编码两者互不干扰。这个看似微小的设计在批量场景下能避免大量报错。5.2 批量循环生成与文件命名主流程其实就是把单张生成的代码包进一个循环里。下面是一个比较完整的批量脚本import os import csv import qrcode import barcode from barcode.writer import ImageWriter os.makedirs(output_qr, exist_okTrue) os.makedirs(output_barcode, exist_okTrue) with open(items.csv, r, encodingutf-8-sig) as f: reader csv.DictReader(f) for row in reader: sku row[sku].strip() qr_content row[qr_content].strip() bar_content row[bar_content].strip() qrcode.make(qr_content).save(foutput_qr/{sku}.png) barcode.get(code128, bar_content, writerImageWriter()).save( foutput_barcode/{sku}, options{ module_width: 0.3, module_height: 12.0, quiet_zone: 6.5, } ) print(f已生成: {sku})这段代码里有几个细节值得说。encodingutf-8-sig是为了兼容Excel另存为CSV时自动添加的BOM头。如果用不带的编码去读第一行第一列会出现一个不可见的\ufeff字符导致第一个SKU文件名变成\ufeffSKU-001.png看起来正常但处理起来很闹心。os.makedirs(..., exist_okTrue)会自动创建输出目录目录已存在时不会报错。这个细节能省掉你反复手动新建文件夹的麻烦。barcode.get(...).save()的保存路径同样不带.pngpython-barcode会自己加扩展名。如果bar_content里碰巧有中文这一步会抛出异常后面的代码块会讲怎么捕获。5.3 批量导出到A4打印拼版批量生成一堆PNG之后下一步通常是打印贴标。如果你直接用系统图片打印功能每张图占一页浪费纸张而且标签大小难控制。更常见的做法是把多个码拼到一张A4纸上。用Pillow做一个简单的拼版功能。以300dpi的A4画布为例尺寸是2480×3508像素。我想在一张A4上放3列×5行共15张标签from PIL import Image import os A4_W, A4_H 2480, 3508 COLS, ROWS 3, 5 MARGIN 80 GAP 30 qr_dir output_qr files sorted(os.listdir(qr_dir)) page Image.new(RGB, (A4_W, A4_H), white) cell_w (A4_W - 2 * MARGIN - (COLS - 1) * GAP) / COLS cell_h (A4_H - 2 * MARGIN - (ROWS - 1) * GAP) / ROWS for idx, filename in enumerate(files): if idx COLS * ROWS: break img Image.open(os.path.join(qr_dir, filename)) # 等比缩放并居中 img.thumbnail((int(cell_w - 20), int(cell_h - 20)), Image.LANCZOS) col idx % COLS row idx // COLS x MARGIN col * (cell_w GAP) (cell_w - img.width) // 2 y MARGIN row * (cell_h GAP) (cell_h - img.height) // 2 page.paste(img, (int(x), int(y))) page.save(qrcode_a4_page1.png)这段代码的本质是“计算格子坐标把图片贴到画布对应位置”。Image.thumbnail()会按比例缩小图片避免长宽变形paste前计算居中偏移保证每张码在格子中间不歪斜。这里有一个要留意的点如果生成的二维码是正方形条形码是宽扁矩形两者拼在同一个格子里时构图差异很大。条形码是用高和宽比来保证可识别性的如果被thumbnail压缩得过小可能会影响扫描所以条形码拼版时建议单独处理给更宽的格子或者直接把两个码画在一张标签图里。6. 常见问题与排查技巧实录6.1 二维码扫不出来的三种情况第一种是尺寸问题。二维码在屏幕上显示没问题一旦打印成实物就扫不出来多半是模块密度过高或打印尺寸过小。比如box_size3的二维码放在手机上看很清晰但打到6号字大小的位置就是一团噪点。排查方法很简单测距手机离二维码20到30厘米扫一下如果对焦都困难把box_size调大或者打印时把物理尺寸放大。第二种是容错率不够。二维码被遮住一部分时低于那个遮罩比例就会失效。比如选了L级容错遮罩只要超过约7%就直接扫描失败。经常遇到的情况是包装上有塑封反光、折痕压过二维码一角。保守方案是统一用H级容错代价是信息容量变小但普通链接通常不受影响。第三种是反色或深色背景。前面提过了二维码只能深内容浅背景。有些人为了设计感把二维码做成深灰底白色块或者把背景做成深蓝这些都会造成识别率断崖式下降。改回黑块白底是最稳妥的没有之一。6.2 条形码识别失败的原因条形码的问题比二维码更多出现在格式和静区上。我排查过不少案例最后归结为五大类现象原因解决办法扫不出来但有条码图像静区不够加大quiet_zone到6.5mm以上扫出来数字不对校验位错误让库自动计算第13位或者13位都核对条码太矮扫不到module_height太小增高到10mm以上打印模糊、条空粘连打印机分辨率不足降低module_width或换200dpi以上打印机含中文导致报错Code128不支持中文中文内容改用二维码条形码用英文/数字编码条形码的“条”和“空”宽度比例是编码规则决定的激光扫描头需要越过黑条和白空来解析宽度。如果打印时墨水洇开黑条变宽白空变窄解析就会失误。所以打印条形码时不要用普通A4纸加墨水喷墨打印机热敏标签机或激光打印机是更靠谱的选择。6.3 中文内容不能直接生成条形码这个坑在批量脚本里尤其致命。Code128虽然支持全部ASCII字符但中文不在其列。如果bar_content是“测试商品01”python-barcode在编码时会对中文字符报编码错误。解决方案有三个一是把中文内容转去生成二维码条形码只放SKU、拼音缩写或数字编号二是自行将中文转成拼音或ASCII码三是改用支持中文的条码标准比如QR Code或者Data Matrix但严格来说它们已经不是传统意义上的条形码了。批量脚本里我会在循环体内单独捕获条形码生成异常不让一个失败的数据把整个流程打断try: barcode.get(code128, bar_content, writerImageWriter()).save(...) except Exception: print(fSKU {sku} 条形码生成失败内容可能含中文)配合一个错误记录文件几百条数据跑完后直接看日志就能定位哪些SKU的数据源要调整不用盯着控制台翻。6.4 几千条数据很慢怎么办批量生成几千条二维码和条形码单线程跑一般也就几分钟瓶颈主要出在PNG编码和文件写入上。多数场景不需要优化但如果数据量到了几万条就要考虑两点。第一输出格式改用SVG。SVG本质是文本生成速度比位图快而且矢量图打印质量更高。第二用多线程并发。Python的concurrent.futures.ThreadPoolExecutor可以把生成任务分发到多个线程IO密集型的图像写入能明显提速。不过要小心线程数不要超过CPU核心数的两倍否则反而会因为上下文切换变慢。实用建议是批量脚本先抽5条样本跑一遍确认图片尺寸、清晰度、文件命名都符合预期再全量跑。全量跑完后再随机抽3到5张用手机和扫码枪实测。生成环节省下来的时间远没有返工浪费时间来得痛。6.5 中文文件名和非法字符问题文件命名时sku列如果有/、:、*、?这类系统非法字符save()时会直接报错。Windows下尤其严格。解决办法是生成文件名前先做一次清洗import re def safe_filename(sku): return re.sub(r[\\/:*?|], _, sku)这个方法会把所有不适合出现在文件名里的字符替换成下划线。这个细节看着小但在真实物料数据里非常常见特别是在SKU设计不规范的老系统里脏数据一堆。7. 这个能力还能往哪扩展如果你已经顺利跑通了批量生成这个能力的扩展空间其实很大。我自己用着比较顺手的方向是给内部工具加一个简单的Web接口用Flask或FastAPI封装一个路由前端输入数据后端动态生成二维码图片返回这样业务同事就不用碰Python代码直接在浏览器页面里操作。本质还是那个库只是把“一句代码”包在了接口里。另外如果你要给非技术同事使用可以用PyInstaller把脚本打包成一个exe可执行文件。打包前把脚本改造成可以接收命令行参数或直接读取固定位置CSV的版本双击即用不用装Python环境。这个实践对团队内的工具交付很有价值我之前把一个物料码批量工具打给仓库同事用极大地减少了中间传话成本。最后分享一个我个人的小习惯不管工具多简单我总会先花一分钟确认“这个码扫出来的是预期内容”。手机扫一下二维码看链接对不对扫码枪试一下条形码看数字对不对再开始批量。批量脚本再快也不如这种马上就能发现问题的验证来得便宜。造码这件事技术难点其实早就被开源库解决了剩下的功夫都花在参数、规范和数据治理上把这些想清楚你的码才能真正好用。
解法)
