批量生成二维码这件事最容易被低估的地方不是“怎么调用二维码库”而是“怎么让一个 WinForm 小工具在真实数据、真实打印机、真实操作员手里稳定跑完几千条”。我这些年做过不少内部资产标签、设备铭牌、物料卡、巡检点标识的小工具需求听起来都很像导入一张表按某一列批量生成二维码保存成 PNG最好还能直接打印。真正落地时坑集中在参数、文件命名、异常数据、UI 卡死、打印模糊和重复覆盖上。这篇就围绕“winform关于批量生二维码的做法”展开把我自己反复踩过的坑和现在比较稳定的实现方式拆开讲。适合手里有 C# 基础、需要在 WinForm 里做离线批量二维码工具的开发者也适合不写代码但需要评估方案的实施人员。1. 先把需求拆开批量二维码不是循环调用生成函数1.1 三条典型业务线决定工具形态我习惯先问一句这批二维码最终贴在哪里、给谁扫、扫出来要看到什么。答案不同工具形态完全不一样。资产标签通常是“编号 名称 部门”二维码内容短重点是文件名能和资产编号对应打印出来耐磨损设备铭牌往往内容更短但可能要求加 Logo、加边框、贴金属表面纠错级别要偏高物料卡和巡检点则更强调批量导入、批量命名、出错可追溯因为一次可能几千条不能生成完才发现中间有几十条是空值。把这三类场景混在一起做界面会越来越臃肿参数也会互相打架。我的做法是先定“最小可用输入”。如果二维码内容只来自一列文本那就支持 TXT 和 CSV 就够了如果客户坚持用 Excel再接 NPOI 或 ClosedXML 读单元格但不要一上来就做复杂模板。输出侧也一样先保证批量 PNG 能稳定落盘再考虑 PDF 拼版、标签打印、自动发邮件。很多工具失败不是功能少而是一开始就想把所有场景吃下结果参数面板十几个选项操作员根本不知道选哪个。还有一个容易忽略的点二维码内容不等于文件名。内容可能是ASSET-2024-0001|打印机|三楼文件名却应该短、可排序、可检索比如00001_ASSET-2024-0001_ab12cd34.png。内容负责被扫码读取文件名负责被人和系统管理这两件事要分开设计。后面讲文件命名时我会给一个可直接用的规则。1.2 为什么在 WinForm 里做而不是临时脚本临时脚本当然快几十行 Python 或 C# 控制台就能跑完。但批量二维码工具的使用者往往不是开发者他们需要选文件、选输出目录、看进度、中途取消、生成完打开文件夹最好还能直接打印。WinForm 的优势就在这里离线、双击即用、文件对话框和打印 API 都是现成的部署到内网电脑也不需要额外开浏览器或装服务。对于“一个月跑一次、一次几千张”的内部工具WinForm 的投入产出比很合适。但 WinForm 也有天然限制。生成二维码是 CPU 和磁盘 IO 混合操作如果你在按钮事件里直接for循环界面必然假死操作员会以为程序崩了然后连点几次按钮最后多个任务同时写同一个目录。另一个限制是绘图资源Bitmap、Graphics、Image这些对象不及时释放跑几千张后 GDI 对象涨上去轻则保存失败重则整个进程异常。所以 WinForm 方案的重点不是“能不能生成”而是“异步、可取消、资源可控、错误可追踪”。技术栈上我一般优先选 .NET 6 或 .NET 8 的 WinForm代码更现代File.ReadAllLinesAsync、Parallel.ForEachAsync都顺手如果甲方环境锁死在 .NET Framework 4.8也能做只是异步文件 API 和并行写法要换一下。选型时不要只看自己电脑要看目标机器有没有对应运行时是否允许安装 NuGet 依赖是否有杀毒软件拦截写文件。这些问题提前问清楚比写完再改省事得多。1.3 生成库选型QRCoder、ZXing.Net 怎么选纯生成二维码我通常选 QRCoder。它是纯 C# 实现MIT 协议生成 PNG、SVG 都方便API 简单依赖少特别适合 WinForm 内部工具。批量场景里我更愿意用它的PngByteQRCode直接拿byte[]写文件绕开Bitmap和GraphicsGDI 泄漏风险小很多。需要中文内容时创建二维码时把forceUtf8打开避免不同扫码器对编码理解不一致。如果项目还需要“生成后自动扫一遍验证”或者要做二维码识别、解码、图片检测那 ZXing.Net 更合适。它生成和解码都能做但 API 相对重一些包也更大。我的常见组合是生产环境用 QRCoder 批量生成测试或质检环节用 ZXing.Net 抽检解码。这样生成端轻验证端独立出问题容易定位。方案强项弱项适用场景QRCoder纯 C#、依赖少、PNG/SVG 方便、批量生成轻不带解码识别WinForm 批量生成、标签导出ZXing.Net生成 解码、生态成熟、可做扫码验证API 偏多、包体相对大需要自动质检、识别已有二维码手写绘图可控性看起来高版本选择、纠错、掩码都要自己处理极易出错学习和实验不建议生产我不建议自己用Graphics画黑白格子来实现二维码。二维码的版本选择、纠错码、掩码、格式信息都有规范手写很容易生成“看起来像二维码但扫不出来”的图。用成熟库把底层规范处理好把精力放在批量流程、参数计算和异常处理上才是划算的做法。2. 二维码参数不是随便填尺寸、纠错、内容长度互相牵制2.1 先定内容再定纠错级别二维码的纠错级别常见有 L、M、Q、H恢复能力大约对应 7%、15%、25%、30%。很多人一上来就选 H觉得越高越好但 H 会增加冗余同样内容需要更多模块二维码更密。标签尺寸固定时模块变小扫码反而更难。我的经验是普通打印标签、内容较短选 M 就够贴在易磨损、油污、金属表面或者中间要放小 Logo选 Q 或 H内容很长、标签又小优先缩短内容而不是硬上高纠错。内容长度也要控制。二维码不是数据库别把整段 JSON、长 URL、几十个字段都塞进去。能放编号就放编号扫码后再用系统查详情。内容越长版本越高模块越多打印出来越密。比如一个资产标签内容用ASSET-2024-0001就够了名称和部门可以印在二维码旁边给人看不必全塞进码里。这样既好扫也方便后期改内容规则。纠错级别大致恢复能力模块密度建议L约 7%最低内容长、屏幕展示、环境干净M约 15%中等默认推荐普通标签够用Q约 25%较高有轻微磨损、油污、需要更稳H约 30%最高金属铭牌、加 Logo、强磨损环境2.2 每模块像素与最终物理尺寸的计算批量生成时最容易犯的错是先生成一张 200×200 的图再拉伸到标签大小。拉伸会插值模块边缘变糊扫码率直线下降。正确做法是先确定最终物理尺寸和打印分辨率再反推每模块像素。计算公式不复杂目标像素宽 ≈ 模块数 × 每模块像素。模块数可以从QRCodeData.ModuleMatrix.Count拿到但不同库对静区处理略有差异所以代码里最好以实际生成后的Width为准或者先试算再微调。举个实际例子。一个 40mm×30mm 的标签用 203dpi 的标签打印机40mm 对应约40 / 25.4 × 203 ≈ 320像素。假设二维码模块数是 25那么每模块 12 像素就是 300 像素放得下每模块 13 像素就是 325 像素可能超边。打印时模块物理边长建议不低于 0.4mm0.5mm 更稳。203dpi 下 0.5mm 约等于 4 个打印点所以每模块至少 4 像素是底线实际标签上我通常留到 8 到 12 像素扫描容错更好。标签宽度打印分辨率可用像素宽模块数示例每模块像素实际像素宽30mm203dpi约 24025820040mm203dpi约 320251230050mm300dpi约 590291852260mm300dpi约 7083320660注意二维码生成后不要再做双线性缩放。需要固定画布时用白色背景加边距不要拉伸二维码本体。打印时如果必须缩放至少用最近邻插值并且先在小批量上实测扫码。2.3 中文、换行、特殊字符和内容模板中文内容不是不能编关键是编码一致。QRCoder 创建二维码时可以设置forceUtf8: true让内容按 UTF-8 处理减少扫码端乱码。CSV 导入时也要注意编码Excel 另存为“CSV UTF-8”通常最稳如果直接读 ANSI CSV中文可能变成问号。TXT 导入我一般要求 UTF-8程序里用Encoding.UTF8读遇到 BOM 也能兼容。内容模板要提前定好分隔符。比如用|分隔字段ASSET-2024-0001|打印机|三楼扫码端按|拆分。不要在内容里随意加换行、制表符、不可见控制字符不同扫码器处理不一致。如果内容本身包含分隔符要么转义要么换一个不常见的分隔符。URL 里有中文参数时先做 URL 编码再放进二维码别直接把原始中文拼进去。特殊字符方面文件名和二维码内容是两套规则。二维码内容可以包含大多数可打印字符但文件名不能包含\ / : * ? |这些字符也不能太长。我的做法是内容照原样编码文件名单独清洗。这样即使内容里有冒号也不会导致保存失败。2.4 文件命名、目录和重复数据批量生成最怕两种事故文件重名互相覆盖以及生成到一半分不清哪批是哪批。我现在固定用“批次目录 序号 清洗后的内容 短哈希”的命名方式。批次目录用时间戳比如20250518_143000每次生成独立目录不覆盖历史结果。文件名用00001_ASSET-2024-0001_ab12cd34.png序号保证排序清洗后的内容方便人看短哈希避免不同内容清洗后重名。重复数据要提前问清楚同样的二维码内容出现两次是生成两张图还是只生成一张资产标签通常每行都要一张哪怕内容重复物料卡可能要求去重。我的默认做法是不去重按行生成但在日志里标记重复内容生成结束后给一个重复统计。这样既不丢行又能让操作员决定要不要清理源数据。命名要素示例作用批次时间20250518_143000隔离每次任务防止覆盖行号00001稳定排序方便对照源表清洗内容ASSET-2024-0001人眼快速识别短哈希ab12cd34防止清洗后重名扩展名.png通用图片格式打印和预览都方便3. WinForm界面与批量流程把“能跑”做成“好用”3.1 界面控件最小集合WinForm 界面不需要花哨但状态要清楚。我通常放这些控件输入文件选择框、输出目录选择框、每模块像素数值框、纠错级别下拉框、生成按钮、取消按钮、进度条、状态标签、日志文本框再加一个“生成后打开目录”的复选框。控件不多但每个都对应一个真实动作。输入路径和输出路径用只读文本框加“浏览”按钮避免操作员手输错路径。纠错级别下拉框可以直接绑定枚举cmbEcc.DataSource Enum.GetValues(typeof(QRCodeGenerator.ECCLevel));。每模块像素用NumericUpDown范围设 4 到 30默认 8 或 10。进度条最大值在任务开始时设置不要固定 100 再换算百分比批量行数就是最直观的进度。日志框用多行只读TextBox不要用ListBox一行行刷几千条会卡。状态管理是关键。生成开始后生成按钮禁用取消按钮启用输入控件禁用任务结束后反过来。不要允许同时开两个生成任务写同一个目录。如果确实需要并发也要在程序层面加锁或给每次任务独立目录。这个小细节能避免大量“文件被占用”“覆盖了一半”的售后问题。3.2 导入数据TXT、CSV、Excel的容错TXT 最简单一行一条内容空行跳过。CSV 要多一步让用户选内容列或者约定第一列就是内容列。读 CSV 时不要用Split(,)硬拆内容里可能有逗号、引号、换行。用成熟的 CSV 解析库或者至少按引号规则处理。编码优先 UTF-8带 BOM 也能读如果用户给的是 GBK给一个编码下拉框别让程序猜。Excel 导入我一般放在第二阶段。用 NPOI 或 ClosedXML 读工作表把单元格统一转成字符串。这里有个坑Excel 会把000123显示成123把长数字变成科学计数法把日期变成数字序列。所以导入前要提示用户把编号列设为文本程序里也要按字符串读不要按数值读。合并单元格、空行、隐藏列都会让行号对不上日志里要记录“源文件行号”方便回去改表。数据校验至少做三件事空内容跳过并记录、超长内容截断或报错、重复内容统计。二维码容量有限内容太长会直接抛异常。与其让任务跑到一半失败不如导入后先做一次预检把空行、超长行、非法字符列出来让用户确认后再生成。这个预检界面不需要复杂一个只读列表加“继续生成”按钮就够。3.3 异步与进度UI线程不能碰生成循环WinForm 的按钮事件运行在 UI 线程生成几千张二维码如果直接循环界面一定卡死。正确写法是async void事件里await Task.Run(...)把批量生成放到后台线程。进度通信用ProgressT它在构造时捕获 UI 同步上下文回调会自动回到 UI 线程更新进度条和标签不需要自己写Invoke。进度刷新不要太频繁。每生成一张就刷一次几千张会让 UI 消息队列堆积反而拖慢速度。我一般每 10 张或每 50 张刷一次最后一张强制刷一次。日志也不要每张都追加成功的不写失败的写最后给汇总。这样界面流畅日志也有用。取消机制要真正生效。用CancellationTokenSource在循环开头ThrowIfCancellationRequested()在文件写入时把 token 传进去。取消后不要立刻删半成品目录保留已经生成的文件和错误日志让操作员知道跑到哪了。等确认不需要后再手动清理。这个细节在真实交付时很重要直接删目录会让人怀疑程序把数据弄丢了。3.4 结果校验和日志生成结束必须给三个数总数、成功数、失败数再加输出目录。失败明细写到_errors.txt或_errors.csv包含源行号、原始内容、异常信息。这样操作员能直接拿源表对照不需要开发人员远程猜。成功文件也可以写一个_manifest.csv记录行号、内容、文件名后续打印或入库都能用。如果项目对质量要求高可以加一个抽检生成完后随机抽 5 到 10 张用 ZXing.Net 解码和原始内容比对。不要全量解码太慢抽检能发现参数配置错、编码错、图片损坏这类系统性问题。抽检不通过就提示“本批次建议不要打印”比打印完几千张再发现扫不出来强得多。4. 关键代码落地从一行文本到一张PNG4.1 NuGet与基础封装先在项目里安装 QRCoder。包管理控制台执行Install-Package QRCoder或者用 NuGet 界面搜索安装。下面代码基于 .NET 6 及以上.NET Framework 4.8 也能用只是异步文件 API 要换成同步版本或自己封装。先定义批量参数和进度对象把输入文件、输出根目录、每模块像素、纠错级别、是否强制 UTF-8 放进去。using QRCoder; public sealed class QrBatchOptions { public string InputFile { get; set; } ; public string OutputRoot { get; set; } ; public int PixelsPerModule { get; set; } 8; public QRCodeGenerator.ECCLevel EccLevel { get; set; } QRCodeGenerator.ECCLevel.M; public bool ForceUtf8 { get; set; } true; } public sealed class QrProgress { public int Done { get; set; } public int Total { get; set; } public string Message { get; set; } ; } public sealed class QrBatchResult { public int Total { get; set; } public int Success { get; set; } public int Failed { get; set; } public string OutputDir { get; set; } ; public Liststring Errors { get; } new Liststring(); }这里把参数封装成对象而不是在方法里传七八个参数后面改配置、加字段都方便。PixelsPerModule默认给 8实际项目里根据标签尺寸调整。ForceUtf8默认打开中文内容更稳。错误列表放在结果对象里UI 层只负责展示不掺和生成逻辑。4.2 批量生成主流程PngByteQRCode避免GDI泄漏批量生成我优先用PngByteQRCode直接拿 PNG 字节数组写文件不经过Bitmap和Graphics。这样即使跑一万张GDI 对象也不会堆积。下面的写法是串行版本稳定、好排查适合先跑通再优化。每张二维码创建QRCodeData后用using释放生成器对象在循环外复用。using System.Text; using System.Text.RegularExpressions; using System.Security.Cryptography; using QRCoder; public sealed class QrBatchService { public async TaskQrBatchResult GenerateAsync( QrBatchOptions opt, IProgressQrProgress progress, CancellationToken token) { var rawLines await File.ReadAllLinesAsync(opt.InputFile, Encoding.UTF8, token); var lines rawLines.Select(x x.Trim()) .Where(x x.Length 0) .ToList(); var batchDir Path.Combine( opt.OutputRoot, DateTime.Now.ToString(yyyyMMdd_HHmmss)); Directory.CreateDirectory(batchDir); var result new QrBatchResult { Total lines.Count, OutputDir batchDir }; var generator new QRCodeGenerator(); int done 0; foreach (var text in lines) { token.ThrowIfCancellationRequested(); try { using var qrData generator.CreateQrCode( text, opt.EccLevel, forceUtf8: opt.ForceUtf8); var pngBytes new PngByteQRCode(qrData) .GetGraphic(opt.PixelsPerModule); var fileName BuildSafeFileName(text, done 1) .png; var fullPath Path.Combine(batchDir, fileName); await File.WriteAllBytesAsync(fullPath, pngBytes, token); result.Success; } catch (OperationCanceledException) { throw; } catch (Exception ex) { result.Failed; result.Errors.Add(${done 1}\t{text}\t{ex.Message}); } finally { done; if (done % 10 0 || done lines.Count) { progress?.Report(new QrProgress { Done done, Total lines.Count, Message $已处理 {done}/{lines.Count} }); } } } await File.WriteAllLinesAsync( Path.Combine(batchDir, _errors.txt), result.Errors, Encoding.UTF8, token); return result; } private static string BuildSafeFileName(string text, int index) { var invalid Path.GetInvalidFileNameChars(); var safe new string(text .Select(c invalid.Contains(c) ? _ : c) .ToArray()); safe Regex.Replace(safe, \s, _); if (safe.Length 24) safe safe.Substring(0, 24); if (safe.Length 0) safe qr; using var sha SHA256.Create(); var hashBytes sha.ComputeHash(Encoding.UTF8.GetBytes(text)); var hash BitConverter.ToString(hashBytes) .Replace(-, ) .Substring(0, 8) .ToLowerInvariant(); return ${index:D5}_{safe}_{hash}; } }这段代码有几个刻意的设计。批次目录用时间戳避免重复运行覆盖旧文件文件名带行号和短哈希既方便排序又避免清洗后重名错误列表最后统一写文件不在循环里频繁开关文件进度每 10 条报一次减少 UI 压力。QRCodeData用完即释放PngByteQRCode不产生 GDI 对象批量稳定性比直接操作Bitmap好很多。4.3 WinForm按钮事件与取消UI 层只做参数收集、任务启动、进度展示和取消。下面是一个可直接套用的按钮事件。注意_cts为空判断防止重复点击Task.Run把批量任务放到后台线程ProgressQrProgress自动回到 UI 线程更新控件。取消按钮只负责Cancel()不要在里面直接关程序或删文件。private CancellationTokenSource? _cts; private async void btnGenerate_Click(object sender, EventArgs e) { if (_cts ! null) return; var opt new QrBatchOptions { InputFile txtInputPath.Text.Trim(), OutputRoot txtOutputDir.Text.Trim(), PixelsPerModule (int)numModulePixels.Value, EccLevel (QRCodeGenerator.ECCLevel)cmbEcc.SelectedItem }; _cts new CancellationTokenSource(); btnGenerate.Enabled false; btnCancel.Enabled true; progressBar1.Value 0; var progress new ProgressQrProgress(p { progressBar1.Maximum p.Total; progressBar1.Value Math.Min(p.Done, p.Total); lblStatus.Text p.Message; }); try { var service new QrBatchService(); var result await Task.Run( () service.GenerateAsync(opt, progress, _cts.Token)); txtLog.AppendText( $完成成功 {result.Success}失败 {result.Failed}目录 {result.OutputDir}{Environment.NewLine}); } catch (OperationCanceledException) { txtLog.AppendText(任务已取消 Environment.NewLine); } catch (Exception ex) { MessageBox.Show(ex.Message, 生成失败); } finally { _cts.Dispose(); _cts null; btnGenerate.Enabled true; btnCancel.Enabled false; } } private void btnCancel_Click(object sender, EventArgs e) { _cts?.Cancel(); }实际项目里还要在启动前校验输入文件存在、输出目录可写、纠错级别已选。不要等任务跑起来再报“路径为空”。如果输出目录在 U 盘或网络盘写文件可能很慢进度会卡在最后几张这时候可以在日志里提示“正在写入磁盘”。不是代码必须但对操作员体验很有帮助。4.4 打印标签时的尺寸换算生成 PNG 只是第一步很多项目最终要打印。WinForm 用PrintDocument可以打但尺寸单位是 1/100 英寸不是毫米。40mm 宽换算成打印单位是40 / 25.4 * 100 ≈ 15730mm 高约118。纸张大小要在开始打印前设置不要等到PrintPage里再改部分打印驱动不认。二维码绘制时用最近邻插值避免模糊。using System.Drawing; using System.Drawing.Drawing2D; using System.Drawing.Printing; private void PrintOneLabel(string imagePath) { int labelWidth (int)(40 / 25.4 * 100); int labelHeight (int)(30 / 25.4 * 100); var doc new PrintDocument(); doc.DefaultPageSettings.PaperSize new PaperSize(Label40x30, labelWidth, labelHeight); doc.DefaultPageSettings.Margins new Margins(0, 0, 0, 0); doc.PrintPage (s, e) { e.Graphics.InterpolationMode InterpolationMode.NearestNeighbor; e.Graphics.PixelOffsetMode PixelOffsetMode.Half; using var img Image.FromFile(imagePath); e.Graphics.DrawImage( img, new Rectangle(0, 0, labelWidth, labelHeight)); e.HasMorePages false; }; doc.Print(); }这段只是单张打印示例。批量打印时不要每张新建PrintDocument而是维护一个待打印列表在PrintPage里取下一张设置HasMorePages。真正上标签打印机前先用普通 A4 打一张看比例再换标签机调 Gap、黑标、浓度。不同打印机驱动对自定义纸张支持不一样必要时让操作员在驱动里建好 40×30 的标签尺寸程序里按驱动名称选纸而不是硬写尺寸。5. 排错与优化批量任务最容易翻车的地方5.1 常见问题速查表批量二维码的故障大多有规律下面这张表是我自己排错时最常翻的。遇到问题先对照现象不要一上来改代码。尤其是“生成成功但扫不出”九成是尺寸、对比度、缩放或内容太长不是库的问题。现象常见原因处理方式中文扫码乱码编码不一致创建时forceUtf8: trueCSV 用 UTF-8生成成功但扫不出模块太小、缩放模糊、对比度低增大每模块像素禁止双线性缩放用纯黑白文件被覆盖文件名重复或输出同一目录批次时间戳目录 行号 短哈希界面卡死在 UI 线程跑循环Task.RunProgressT跑几千张后报错GDI 对象或文件句柄泄漏用PngByteQRCodeusing释放资源路径过长文件名太长或目录太深文件名截断到 24 字符内输出根目录别太深Excel 编号变数字单元格被识别为数值编号列设为文本程序按字符串读打印模糊生成图被拉伸或打印机分辨率低按打印 DPI 生成最近邻插值取消没反应循环没检查 token循环开头和写文件时传 token网络盘写入慢IO 瓶颈先写本地临时目录完成后再复制权限拒绝输出目录不可写换目录或提升权限启动时预检重复内容处理不清业务规则未定默认按行生成日志统计重复5.2 内存与GDI对象泄漏排查WinForm 里最容易忽略的是 GDI 对象。用Bitmap生成二维码时Bitmap、Graphics、Image都要及时释放。更隐蔽的是Image.FromFile它会在图片文件上保持句柄直到图片对象被回收导致文件删不掉、覆盖失败。批量场景我干脆不用Bitmap生成直接用PngByteQRCode写字节数组从源头减少 GDI 对象。需要预览时再单独加载一张小图预览完立即释放。如果已经用了Bitmap排查方式是看任务管理器里的 GDI 对象数跑一百张看是否持续上涨。上涨就找没using的Graphics、Pen、Brush、Bitmap。另一个办法是生成一批后手动删输出目录如果提示“文件被占用”基本就是图片或文件流没释放。File.WriteAllBytesAsync内部会自己关闭文件比手写FileStream省心但前提是你没有别的地方还开着同一个文件。5.3 大批量生成的速度优化串行生成一千张通常够用一万张就要考虑优化。瓶颈一般在磁盘 IO不在二维码计算。优化顺序我一般是先用PngByteQRCode去掉 GDI 开销再把进度刷新降到每 50 张一次然后按 CPU 核数开并行但不要开满Environment.ProcessorCount / 2起步观察磁盘和 CPU 再调。并行时每个线程用自己的QRCodeGenerator不要共享可变对象避免线程安全问题。using System.Collections.Concurrent; using System
