绝大多数场景下无需生成PDF条形码，只需插入高DPI（300dpi）PNG图片；跨平台应弃用依赖GDI+的BarcodeWriter，改用SkiaSharp+ZXing.Net的BarcodeWriterGeneric，并显式设置Format、Width、Height和Margin=0。
用 BarcodeWriter 生成 PDF 条形码前，先确认你真需要“PDF”还是只要“图片”
绝大多数场景下，你不是在生成 PDF 文件，而是在往 PDF 文档里插入条形码图片（比如用 iTextSharp 或 QuestPDF 生成报告时）。直接调用 BarcodeWriter.Write() 返回的是 Bitmap 或 byte[]，不是 PDF。强行塞进 PDF 渲染流程却忽略 DPI、缩放、抗锯齿，结果就是条形码扫不出——这是最常被忽略的前提。
实操建议：
- 如果只是导出单个条形码图：用
BarcodeWriter输出Bitmap，再Save(..., ImageFormat.Png)即可，别碰 PDF 库 - 如果要嵌入到 PDF 报告中：选支持矢量渲染的库（如
QuestPDF+SkiaSharp），或把Bitmap转成高 DPI（300dpi）PNG 再插入 - 别用
MemoryStream直接写进 PDF 的Image字段却不指定尺寸单位——iTextSharp 默认按点（point）解析，而Bitmap.Width是像素，不换算会严重变形
SkiaSharp + ZXing.Net 组合比纯 BarcodeWriter 更稳
ZXing.Net 自带的 BarcodeWriter 依赖 GDI+，Windows 上没问题，但 .NET 6+ 跨平台部署（Linux Docker）时容易因缺少字体或图像编码器崩溃，错误信息通常是 System.PlatformNotSupportedException: System.Drawing is not supported on this platform。
实操建议：
- 改用
ZXing.Net的BarcodeWriterGeneric<SKBitmap>，底层走SkiaSharp，无 GDI+ 依赖 - 初始化时显式指定格式：
new BarcodeWriterGeneric<skbitmap> { Format = BarcodeFormat.CODE_128 }</skbitmap>，不靠默认值 - 设置
Options.Width和Options.Height必须是整数，且 ≥ 最小模块宽度（CODE128 通常 ≥ 2），否则Write()返回空SKBitmap - 别漏掉
Options.Margin = 0——默认有 10px 白边，PDF 里留白太多会导致扫码器识别失败
PDF 插入条形码后扫不出来？先查这三点
不是代码没跑通，而是 PDF 渲染层悄悄破坏了条形码结构。常见于文字叠加、压缩失真、颜色反色。
实操建议：
- 用 Adobe Acrobat 的“输出预览”检查实际嵌入的图像是否为 RGB 模式，CMYK 或灰度可能让黑白对比度不足
- 确认 PDF 插入时没启用“自动压缩图像”，iTextSharp 的
PdfContentByte.AddImage()默认开启，得手动关：img.SetDpi(300, 300); img.CompressionLevel = 0; - 避免在条形码区域加半透明遮罩或阴影效果——PDF 渲染器会混合像素，导致模块边界模糊
- 测试时别只用手机相册打开 PDF 截图扫码，要用专业扫码 App（如 Barcode Scanner）直读 PDF 页面
别用 System.Drawing.Common 在 Linux 容器里生成条形码
哪怕你加了 <packagereference include="System.Drawing.Common" version="8.0.0"></packagereference> 并装了 libgdiplus，BarcodeWriter 在 Alpine 容器里仍大概率报 Unable to load shared library 'libgdiplus' 或静默返回空白图。这不是配置问题，是架构级不兼容。
实操建议：
- 容器镜像改用
mcr.microsoft.com/dotnet/aspnet:8.0-jammy（Ubuntu 基础），它预装了完整图形栈 - 或者彻底放弃
System.Drawing，所有条形码路径都走SkiaSharp+ZXing.Net组合 - CI/CD 构建阶段加一行验证：
dotnet test --filter "FullyQualifiedName~Barcode"，确保生成逻辑在目标环境能跑通
真正麻烦的从来不是“怎么画出来”，而是“画出来的能不能被机器准确读取”。PDF 的渲染链路太长，每个环节都可能吃掉一个像素——少一个模块，整个码就废了。
