QuestPDF需先注册中文字体再生成PDF，iTextSharp 5.x不支持.NET Core+，选型需权衡团队熟悉度、PDF复杂度及许可证；调试时须检查流生命周期、字体路径和Content-Type。
QuestPDF 创建 PDF 的基本流程
QuestPDF 是现代、声明式、基于 .NET 6+ 的 PDF 生成库，语法接近 Blazor，适合需要可读性强、维护性高的 PDF 模板场景。它不依赖外部引擎或系统字体，但默认使用嵌入的 LiberationSans 字体，中文需手动注册字体。
常见错误是直接写中文却没注册中文字体，结果输出空白或方块：
Document.Create(container =>
{
container.Page(page =>
{
page.Content().Element(e => e.Text("你好世界")); // ❌ 默认不支持中文
});
}).GeneratePdf("output.pdf");正确做法：
- 下载一个支持中文的 TrueType 字体（如
NotoSansCJKsc-Regular.otf），放入项目Resources/Fonts/目录，并设为Copy to Output Directory - 在生成前调用
FontCollection.Default.Register注册字体：
FontCollection.Default.Register(Path.Combine(AppContext.BaseDirectory, "Resources", "Fonts", "NotoSansCJKsc-Regular.otf"));
Document.Create(...).GeneratePdf("output.pdf");注意：Register 必须在 Document.Create 之前执行，且只执行一次；重复注册会抛出 InvalidOperationException。
iTextSharp 5.x 生成 PDF 的关键限制
iTextSharp 5.x（即旧版，MIT 许可）仍被大量遗留项目使用，但它不支持 .NET Core/.NET 5+ 的原生运行，只能用于 .NET Framework 4.6.1+ 项目。若你在 .NET 6+ 中引用 iTextSharp 5.x，编译可能通过，但运行时会报 System.IO.FileNotFoundException: Could not load file or assembly 'itextsharp'。
真正能跨平台的是 iText7（商业许可较严，免费版有水印限制），而很多人搜 “iTextSharp” 实际想用的是它——这是最常踩的兼容性坑。
如果你坚持用 iTextSharp 5.x：
- 确认目标框架是
<targetframework>net472</targetframework>或类似 - 用 NuGet 安装
iTextSharp.LGPLv2.Core（社区维护的开源分支，支持 .NET Standard 2.0）而非原始iTextSharp - 中文仍需
BaseFont.CreateFont加载字体，且必须用CP1252以外的编码（如Identity-H）
示例片段（使用 LGPLv2.Core）：
var font = BaseFont.CreateFont("STHeiti Light.ttc,0", BaseFont.IDENTITY_H, BaseFont.NOT_EMBEDDED);
var fontChinese = new Font(font, 12);
ColumnText.ShowTextAligned(writer.DirectContent, Element.ALIGN_LEFT, new Phrase("你好世界", fontChinese), 50, 750, 0);QuestPDF vs iText7：选型看这三点
不是“哪个更好”，而是“哪个更匹配你的约束”：
- 团队熟悉度：若已有 Blazor 或 LINQ 经验，QuestPDF 的链式 + lambda 写法上手更快；iText7 的 API 更底层，接近 Java iText，文档以 Java 为主，C# 示例少
- PDF 复杂度：表格嵌套、页眉页脚动态计算、分栏布局，QuestPDF 声明式语法更直观；但需要精确控制每个字节（如数字签名、PDF/A 合规）、或复用现有 iText Java 逻辑时，iText7 更可控
-
许可证与部署：QuestPDF 完全 MIT 开源，无 runtime 限制；iText7 的
itext7.kernel等核心包在 AGPL 下免费，但商用需购买许可证（否则生成的 PDF 会带水印）
一个容易被忽略的事实：QuestPDF 默认生成 PDF 1.7，iText7 默认 PDF 2.0；某些老旧 PDF 阅读器（如 Windows 自带阅读器旧版）对 PDF 2.0 支持不完整，导出失败却不报错，只显示空白页。
调试 PDF 输出失败的三个检查点
无论用哪个库，PDF 文件生成后打不开 / 显示为空白 / 提示“已损坏”，优先查：
-
FileStream是否被提前Dispose？比如在using (var fs = new FileStream(...)) { ... GeneratePdf(fs); }中，GeneratePdf若异步或延迟写入，fs可能已关闭 → 改用GeneratePdf(Stream)时确保流生命周期覆盖整个写入过程 - 字体路径是否为绝对路径？
Path.Combine(AppContext.BaseDirectory, "...")在单元测试或某些部署环境下（如 ClickOnce）可能指向意外位置 → 建议先用File.Exists(...)断言 - 是否在 ASP.NET Core 中返回 PDF 时忘了设置
Content-Type？return File(bytes, "application/pdf", "report.pdf")比return Content(..., "text/plain")少一半乱码问题
QuestPDF 的 GeneratePdf 方法内部不做异常吞并，但 iText7 的 PdfWriter 构造失败可能静默返回 null——务必检查返回值或启用日志（PdfWriter.SetDebugMode(true)）。
