PDF 转图片只需一行代码:PDFtoImage

仓库：

https://github.com/sungaila/PDFtoImage

一、核心功能

一行代码完成转换

提供 PDFtoImage.Conversion 静态类，一行代码即可将 PDF 页面渲染为图片：

Conversion.SaveJpeg("output.jpg", File.OpenRead("input.pdf"));

多输入源支持

项目提供三套原生输入 API，外加一种常用便捷写法，覆盖不同场景：

• Stream
  ToImage(Stream pdfStream) —— 适合 ASP.NET 上传文件直接处理
• Base64
  ToImage(string pdfAsBase64String) —— 适合 Web API / Blazor 前端传参
• byte[]
  ToImage(byte[] pdfAsByteArray) —— 适合内存中已有 PDF 字节数组的场景
• 文件路径（便捷写法）
  Conversion.SaveJpeg("output.jpg", File.OpenRead("input.pdf")) —— 通过 File.OpenRead 包装为 Stream，适合批量脚本处理

多格式输出

• SaveJpeg
   / ToImage → JPEG 或 SKBitmap 对象
• SavePng
   → PNG
• SaveWebp
   → WebP

单页与批量

• 单页
  ToImage(pdfStream, page: 0) 返回单张 SKBitmap
• 批量
  ToImages(pdfStream) 返回 IEnumerable<SKBitmap>，配合 Range 语法 ToImages(pdfStream, 0..5) 可选页
• 异步流
  （.NET 6+）：ToImagesAsync(pdfStream) 返回 IAsyncEnumerable<SKBitmap>，适合流式处理

密码保护 PDF

所有方法均支持 password 参数，可处理加密文档。

二、技术架构

┌─────────────────────────────────────────────────┐│              公共 API (Conversion 类)              ││                                                   ││  SaveJpeg  SavePng  SaveWebp  ToImage  ToImages   ││  GetPageCount  GetPageSizes  GetPageSize          ││                                                   ││  ┌───────────┐  ┌──────────┐  ┌───────────────┐ ││  │ Stream    │  │ Base64   │  │ byte[]        │ ││  │ 输入      │  │ 输入     │  │ 输入          │ ││  └─────┬─────┘  └────┬─────┘  └──────┬────────┘ │└────────┼─────────────┼───────────────┼──────────┘         │             │               │         ▼             ▼               ▼┌─────────────────────────────────────────────────┐│              内部层 (Internals)                    ││                                                   ││  PdfLibrary ──► PdfDocument ──► PdfFile          ││  StreamManager  LibraryLoader  NativeMethods      ││  (锁保护：PDFium 非线程安全)                        ││                                                   │└─────────┬───────────────────────────┬───────────┘          │                           │    ┌─────┴─────┐             ┌───────┴───────┐    ▼           ▼             ▼               ▼┌─────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐│ PDFium  │ │ PDFium     │ │ SkiaSharp│ │ SkiaSharp││ Windows │ │ Linux/macOS│ │ Encode   │ │ Render   ││ PDFium  │ │ Android/iOS│ │ (JPEG/   │ │ (DPI/    ││ Blazor  │ │ Unity      │ │ PNG/WebP)│ │ Tiling)  │└─────────┘ └────────────┘ └──────────┘ └──────────┘

PDFium 是 Google 的原生 PDF 渲染引擎（Chrome / Chromium 内置），SkiaSharp 是跨平台 2D 图形 API（Mono/.NET Foundation 项目）。PDFtoImage 将两者结合，实现从 PDF 解析到图片输出的完整管线。

三、RenderOptions：13 项渲染配置

所有输出方法均接受 RenderOptions 参数，以 readonly record struct 形式提供 13 个可配置项：

using SkiaSharp;using PDFtoImage;var options = new RenderOptions(    Dpi: 150, Width: 800,    WithAspectRatio: true, Rotation: PdfRotation.Rotate90,    AntiAliasing: PdfAntiAliasing.All, BackgroundColor: SKColors.Black,    Grayscale: true);

四、安装与使用

NuGet 安装

dotnet add package PDFtoImage

基础示例

using System;using System.IO;using PDFtoImage;using SkiaSharp;// 单页转 JPEG，保存为文件Conversion.SaveJpeg("page1.jpg", File.OpenRead("document.pdf"));// 单页转 PNG，输出为 Streamusingvar output = new MemoryStream();Conversion.SavePng(output, File.OpenRead("document.pdf"));// 批量转换为 SKBitmapforeach (var bitmap in Conversion.ToImages(File.OpenRead("document.pdf"))){// bitmap.Encode(stream, SKEncodedImageFormat.Jpeg, 90);}

.NET 6+ 异步流

// 处理全部页面awaitforeach (var bitmap in Conversion.ToImagesAsync(File.OpenRead("large.pdf"))){// bitmap.Encode(stream, SKEncodedImageFormat.Jpeg, 90);}// 处理指定范围页面（0 到倒数第 1 页，即跳过最后一页）awaitforeach (var bitmap in Conversion.ToImagesAsync(    File.OpenRead("large.pdf"), 0..^1)){// 逐页处理，不阻塞}

Unity 安装

在 Unity Package Manager 中，选择 Install package from git URL，输入：

https://github.com/sungaila/PDFtoImage.git?path=etc/UnityPackage

五、多框架支持

⚠️ iOS 平台在 MAUI 和 Unity 下暂不支持（受 PDFium 原生库限制）。

六、平台支持

七、API 参考

Conversion 静态类核心方法

错误类型

项目定义了 7 种专用异常：

• PdfException
   — 基础异常类
• PdfCannotOpenFileException
   — 无法打开 PDF 文件
• PdfInvalidFormatException
   — PDF 格式无效
• PdfPageNotFoundException
   — 页面不存在
• PdfPasswordProtectedException
   — 密码保护
• PdfUnknownException
   — 未知错误
• PdfUnsupportedSecuritySchemeException
   — 不支持的安全方案

八、WebConverter 演示

项目附带一个完整的 Blazor Web 演示应用（src/WebConverter/），提供：

• PDF 文件上传界面
• 在线预览转换结果
• 支持 JPEG / PNG / WebP 格式输出
• Base64 传输模式

可直接运行体验 PDFtoImage 在 Web 端的完整功能。

九、注意事项

无并行化支持

PDFium 原生库不是线程安全的。PDFtoImage 通过内部锁保护所有 PDFium 调用，这意味着同一时刻只能处理一个 PDF。

如需并行处理，需启动多个进程并分配任务。

瓦片渲染

对于超大页面（例如 A0 尺寸 600 DPI），输出图片可能超出内存限制。启用 UseTiling = true 可将 PDF 分块渲染后合并，避免崩溃。

十、项目结构

PDFtoImage/├── src/│   ├── PDFtoImage/                 # 核心库│   │   ├── Conversion.cs           # 渲染核心（公共方法）│   │   ├── Conversion.Base64.cs    # Base64 输入 API│   │   ├── Conversion.ByteArray.cs # byte[] 输入 API│   │   ├── Conversion.Stream.cs    # Stream 输入 API│   │   ├── RenderOptions.cs        # 渲染配置 record struct│   │   ├── PdfAntiAliasing.cs      # 抗锯齿枚举│   │   ├── PdfRotation.cs          # 旋转枚举│   │   ├── IRenderOptions.cs       # 渲染接口│   │   ├── Internals/│   │   │   ├── PdfDocument.cs      # PDF 文档封装（含瓦片渲染）│   │   │   ├── PdfFile.cs          # PDFium 文件加载│   │   │   ├── PdfLibrary.cs       # PDFium 初始化│   │   │   ├── NativeMethods.cs    # P/Invoke 声明│   │   │   ├── StreamManager.cs    # 流管理│   │   │   ├── LibraryLoader.cs    # 动态库加载│   │   │   └── MonoPInvokeCallbackAttribute.cs│   │   └── Exceptions/             # 7 种专用异常│   ││   ├── Tests/                      # 单元测试│   │   ├── ApiTests.cs             # API 测试│   │   ├── AntiAliasingTests.cs    # 抗锯齿测试│   │   ├── AspectRatioTests.cs     # 宽高比测试│   │   ├── BackgroundColorTests.cs # 背景色测试│   │   ├── BatchingTests.cs        # 批量测试│   │   ├── BoundsTests.cs          # 边界测试│   │   ├── ComparisonTests.cs      # 对比测试│   │   ├── ExceptionTests.cs       # 异常测试│   │   ├── FormFillTests.cs        # 表单填充测试│   │   ├── PasswordTests.cs        # 密码测试│   │   ├── QueryTests.cs           # 查询测试│   │   ├── RotationTests.cs        # 旋转测试│   │   └── TilingTests.cs          # 瓦片渲染测试│   ││   ├── FrameworkTests/             # 框架集成测试│   │   ├── AspNet/                 # ASP.NET 测试│   │   ├── AspNetCore/             # ASP.NET Core 测试│   │   ├── MauiApp/                # MAUI 测试│   │   ├── Unity2D/                # Unity 测试│   │   └── AotConsole/             # AOT 兼容测试│   └── WebConverter/               # Blazor Web 演示应用│       ├── Client/                 # Blazor 客户端│       ├── Pages/                  # Razor 页面│       └── Models/                 # 数据模型│├── etc/│   ├── UnityPackage/               # Unity 安装包│   └── Icon*.png                   # 项目图标│├── .github/workflows/              # CI/CD│   ├── dotnet.yml                  # .NET 构建 + 测试│   ├── codeql.yml                  # CodeQL 安全扫描│   └── githubpages.yml             # GitHub Pages 部署│├── PDFtoImage.csproj               # 多目标框架项目文件（12 个 TFM）├── README.md                       # 项目文档└── LICENSE                         # MIT 许可证

十一、项目信息

• 名称
  PDFtoImage
• 版本
  5.2.1
• 技术栈
  PDFium + SkiaSharp + C#
• 许可证
  MIT 
• 仓库
  https://github.com/sungaila/PDFtoImage
• NuGet
  https://www.nuget.org/packages/PDFtoImage/
• 网站
  https://www.sungaila.de/PDFtoImage/
• 目标框架
  .NET 8-10 / .NET Framework 4.7.1+ / .NET Standard 2.1 / Android / iOS / MacCatalyst / WASM
• 支持框架
  ASP.NET / ASP.NET Core / Blazor WASM / .NET MAUI / Unity / UWP / WinUI 3

本文仅为开源项目介绍。更多使用细节和反馈请前往 GitHub 仓库。