前言

发运单打印——听起来再寻常不过的一个功能，真要动手做的时候，麻烦事一个接一个。中文乱码、表格对不齐、二维码扫不出来、在Windows上跑得好好的丢到Linux服务器上直接崩溃……这些问题单独拎出来都不算大，但凑在一起足够让人折腾一整天。

本文记录了一套从零搭建的发运单PDF生成方案，基于.NET 10和PdfSharpCore，把踩过的坑和绕过的弯路都摊开来讲。整套代码可以直接拿过去用，不需要改太多就能跑起来。

项目介绍

这套方案解决的是一个很具体的问题：物流系统里高频出现的发运单PDF生成。输入是一个结构化的运单数据，输出是一份排版整齐、带二维码、支持中文的PDF文件。

选PdfSharpCore作为底层库，原因很实在——它是MIT协议，没有版权顾虑；支持.NET Standard，Windows和Linux都能跑；画布式的绘图API虽然原始，但对发运单这种布局固定的场景反而顺手，每一像素都在掌控之内，不需要折腾HTML模板和浏览器渲染。

项目功能

生成A4尺寸的发运单PDF，布局固定、字段完整

自动绘制发货方、收货方、承运商、运单号等信息区

货物明细表格动态生成，支持多行数据展示

合计行自动计算总数量和总重量

右上角生成运单号二维码，下方附带运单号文字

底部预留签收区域（签字、日期、备注）

生成的PDF直接输出为字节数组，便于接口返回或存储

项目特点

跨平台部署：基于.NET Standard，在Windows、Linux、macOS上行为一致，Docker容器中也能稳定运行

中文原生支持：通过自定义字体解析器显式加载.ttf字体文件，不依赖系统已安装字体

二维码内嵌：纯C#生成二维码，无需额外图形库，输出PNG字节流直接绘入PDF

低依赖：仅需两个NuGet包（PdfSharpCore和QRCoder），没有繁琐的第三方组件

高性能：纯内存操作，不涉及文件IO（二维码图片用临时文件绕开了PdfSharpCore的一个流处理限制，用完即删）

可扩展：表格列宽、边距、字体大小等参数全部硬编码但集中管理，按需调整即可

项目技术

项目代码

环境准备

创建项目后，先安装两个核心包：

dotnet add package PdfSharpCore --version 1.3.67dotnet add package QRCoder --version 1.8.0

项目目标框架设置为net10.0。

中文字体处理（最关键的一步）

PdfSharpCore默认不支持中文，需要自己注册字体。把simhei.ttf（黑体）放到项目的Fonts/目录下，设置复制到输出目录，然后实现自定义字体解析器：

using PdfSharpCore.Fonts;publicclassCustomFontResolver : IFontResolver{privatestaticreadonlystring FontPath = Path.Combine(        AppDomain.CurrentDomain.BaseDirectory, "Fonts", "simhei.ttf"    );publicstring DefaultFontName => "ChineseFont";publicbyte[] GetFont(string faceName)    {return File.ReadAllBytes(FontPath);    }public FontResolverInfo ResolveTypeface(string familyName, bool isBold, bool isItalic)    {returnnew FontResolverInfo("ChineseFont");    }}

程序启动时注册：

GlobalFontSettings.FontResolver = new CustomFontResolver();

注意：这里只认.ttf格式，.ttc文件会导致解析失败。Windows系统自带的simhei.ttf一般在C:\Windows\Fonts\目录下，复制出来放进项目即可。

数据模型

publicclassShippingOrder{publicstring OrderNo { get; set; } = string.Empty;publicstring Sender { get; set; } = string.Empty;publicstring SenderAddress { get; set; } = string.Empty;publicstring Receiver { get; set; } = string.Empty;publicstring ReceiverAddress { get; set; } = string.Empty;publicstring ReceiverPhone { get; set; } = string.Empty;public DateTime ShipDate { get; set; }publicstring Carrier { get; set; } = string.Empty;public List<ShippingItem> Items { get; set; } = new();}publicclassShippingItem{publicstring Name { get; set; } = string.Empty;publicstring Spec { get; set; } = string.Empty;publicint Quantity { get; set; }publicstring Unit { get; set; } = string.Empty;publicdecimal Weight { get; set; }publicstring Remark { get; set; } = string.Empty;}

核心生成器

完整的PDF绘制逻辑封装在ShippingLabelGenerator类中，主要包含以下几个部分：

1. 标题绘制

居中显示"发 运 单"，下方画一条分割线。

2. 右上角二维码

二维码的生成用的是QRCoder，先得到PNG字节数组，再写入临时文件，通过XImage.FromFile载入到PDF中。之所以绕一道临时文件，是因为PdfSharpCore的XImage.FromStream在部分版本上有流状态的问题，用文件方式更稳定。

二维码固定在页面右上角，大小80×80，下方紧挨着显示运单号文本。

privatevoidDrawQrCode(XGraphics gfx, XFont font, string content){usingvar qrGenerator = new QRCodeGenerator();usingvar qrData = qrGenerator.CreateQrCode(content, QRCodeGenerator.ECCLevel.M);var base64QR = new Base64QRCode(qrData);byte[] pngBytes = Convert.FromBase64String(base64QR.GetGraphic(8));var tmpPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, $"qr_{Guid.NewGuid():N}.png");try    {        File.WriteAllBytes(tmpPath, pngBytes);usingvar xImg = XImage.FromFile(tmpPath);double qrSize = 80;double qrX = MarginLeft + ContentWidth - qrSize;double qrY = MarginTop;        gfx.DrawImage(xImg, qrX, qrY, qrSize, qrSize);// 下方标注运单号var labelRect = new XRect(qrX, qrY + qrSize + 2, qrSize, 12);        gfx.DrawString(content, font, XBrushes.Black, labelRect, XStringFormats.Center);    }finally    {if (File.Exists(tmpPath)) File.Delete(tmpPath);    }}

3. 发货/收货信息区

分为左右两列，左列显示发货方、发货地址、发货日期，右列显示收货方、收货地址、联系电话。下方再单独一行显示承运商和运单号。

4. 货物明细表格

表格列宽根据内容做了分配：品名160、规格80、数量55、单位45、重量70、备注105（单位是"点"，A4纸宽约595点）。

表头带灰色背景，数据行交替无背景（这里没有做隔行变色，保持简洁）。最后一行为合计行，灰色背景，显示总件数和总重量。

5. 签收区

底部绘制三条信息：收货人签字、签收日期、备注框。备注后面画了一个矩形框用于手写补充信息。

调用示例

var order = new ShippingOrder{    OrderNo = "SF2025050300001",    Sender = "华科电子科技有限公司",    SenderAddress = "广东省深圳市南山区科技园A栋5F",    Receiver = "李四",    ReceiverAddress = "北京市朝阳区建国路88号",    ReceiverPhone = "139****9999",    ShipDate = DateTime.Today,    Carrier = "顺丰速运",    Items = new List<ShippingItem>    {new ShippingItem { Name = "温湿度传感器", Spec = "TH-200", Quantity = 8, Unit = "个", Weight = 0.8m },new ShippingItem { Name = "数据采集主机", Spec = "DAQ-3000", Quantity = 3, Unit = "台", Weight = 5.5m, Remark = "防震" },new ShippingItem { Name = "通讯线缆", Spec = "RS485/10m", Quantity = 15, Unit = "根", Weight = 2.1m }    }};var generator = new ShippingLabelGenerator();byte[] pdfBytes = generator.Generate(order);File.WriteAllBytes("shipping_label.pdf", pdfBytes);

项目效果

生成的PDF效果大致如下：

• 标题"发 运 单"居中显示，带下划线

• 右上角二维码清晰可扫，下方显示运单号

• 发货方和收货方信息左右对齐，字段整齐

• 表格边框完整，表头加灰底突出显示

• 合计行自动汇总数量和重量

• 底部签收区域留白充足，符合纸质单据的使用习惯

项目源码

完整的源码结构：

AppPdfSharpCoreDelivery/├── Program.cs                # 入口，构造数据并调用生成器├── ShippingOrder.cs          # 数据模型定义├── ShippingLabelGenerator.cs # PDF生成核心逻辑├── CustomFontResolver.cs     # 中文字体解析器├── Fonts/│   └── simhei.ttf            # 中文字体文件（需手动放入）└── AppPdfSharpCoreDelivery.csproj

源码中已经处理了几个容易踩坑的地方：

• 字体解析器同时兼容Windows和Linux路径

• 二维码生成用临时文件绕开XImage.FromStream的坑

• 表格绘制时先填充背景色再画边框（分两次调用）

• Y轴坐标累加方向正确，内容不会重叠

• 临时二维码图片用完立即删除，不留垃圾文件

总结

这套发运单生成方案的核心思路很简单：把PDF当作一块画布，用坐标逐个元素往上画。没有模板引擎的灵活性，但换来的是稳定可预测的输出结果和极低的运行开销。

实际使用时最需要注意的就是中文字体的注册，只要字体文件打包正确、解析器实现无误，中文显示就不会出问题。二维码部分用QRCoder生成PNG再载入，避开了PdfSharpCore原生图片支持的一些边界情况。

整个方案已经在实际项目中用了一段时间，Windows服务器和Linux Docker容器都跑过，没有遇到跨平台相关的异常。如果你的业务场景也需要生成布局固定的单据PDF，这套代码可以直接拿过去用，根据实际字段调整一下坐标和列宽就行。

关键词

#PdfSharpCore、.NET 10、#发运单打印、#PDF生成、#中文乱码、#二维码嵌入、#跨平台部署、#字体解析器、#QRCoder、SixLabors.Fonts、物流单据、Docker部署

觉得有收获？不妨分享让更多人受益

关注「DotNet技术匠」，共同提升技术实力