跳到主要内容

go 转图片 高性能pdf 转pdf 详解

· 阅读需 8 分钟
ahKevinXy
ahKevinXy
作者

开源库go-fitz

o 语言实现高性能 PDF 转图片的完整方案，包含核心原理、性能优化、完整代码、避坑指南，兼顾「易用性」和「高性能」，新手也能直接落地。

一、核心原理与技术选型​

1. PDF 转图片的核心逻辑​

PDF 转图片本质是：

  1. 解析 PDF 文件，提取每页的页面数据；
  2. 将页面数据渲染为位图（RGB/PNG/JPG）；
  3. 输出/保存图片文件。

2. 技术选型（高性能优先）​

Go 生态中 PDF 处理的主流库对比：

库核心优势性能跨平台依赖适用场景
github.com/gen2brain/go-fitz基于 MuPDF（高性能渲染）高是静态库高性能批量转换、生产环境
github.com/pdfcpu/pdfcpu纯 Go 实现、轻量中是无简单转换、无依赖部署
gopdf/unipdf功能全、支持编辑中是无需同时编辑 PDF 的场景

✅ 推荐选型：go-fitz（基于 MuPDF）—— 渲染速度快、画质高，是高性能场景的首选。

3. 前置依赖（go-fitz）​

go-fitz 依赖 MuPDF 静态库，不同系统安装方式：

# Linux（Debian/Ubuntu）
sudo apt install libmupdf-dev

# macOS
brew install mupdf

# Windows
# 下载预编译的 mupdf 静态库，放入系统库目录（或直接用预编译的 go-fitz 版本）

安装 go-fitz：

go get github.com/gen2brain/go-fitz

二、高性能 PDF 转图片（完整代码）​

1. 基础版（单页/多页转换）​

实现「PDF 按页转图片」，支持自定义分辨率、图片格式、输出路径：

package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/gen2brain/go-fitz"
)

// PDFToImage PDF 转图片核心函数
// pdfPath: PDF 文件路径
// outputDir: 图片输出目录
// dpi: 分辨率（越高越清晰，推荐 150-300）
// imgFormat: 图片格式（png/jpg）
func PDFToImage(pdfPath, outputDir string, dpi int, imgFormat string) error {
	// 1. 检查输出目录，不存在则创建
	if err := os.MkdirAll(outputDir, 0755); err != nil {
		return fmt.Errorf("创建输出目录失败：%v", err)
	}

	// 2. 打开 PDF 文件
	doc, err := fitz.New(pdfPath)
	if err != nil {
		return fmt.Errorf("打开 PDF 失败：%v", err)
	}
	defer doc.Close() // 延迟关闭，释放资源

	// 3. 获取 PDF 总页数
	totalPages := doc.NumPage()
	fmt.Printf("PDF 总页数：%d，开始转换...\n", totalPages)

	// 4. 遍历每页转换
	for pageNum := 0; pageNum < totalPages; pageNum++ {
		// 4.1 渲染页面为图片（dpi 控制分辨率）
		img, err := doc.Image(pageNum, dpi)
		if err != nil {
			return fmt.Errorf("第 %d 页渲染失败：%v", pageNum+1, err)
		}

		// 4.2 构造输出文件名（如：output/1.png）
		imgName := fmt.Sprintf("%d.%s", pageNum+1, imgFormat)
		imgPath := filepath.Join(outputDir, imgName)

		// 4.3 创建文件并写入图片
		f, err := os.Create(imgPath)
		if err != nil {
			return fmt.Errorf("创建图片文件失败：%v", err)
		}
		defer f.Close()

		// 4.4 编码并保存图片（根据格式选择编码方式）
		switch imgFormat {
		case "png":
			if err := png.Encode(f, img); err != nil {
				return fmt.Errorf("第 %d 页 PNG 编码失败：%v", pageNum+1, err)
			}
		case "jpg":
			// 质量 90（0-100，越高越清晰）
			jpeg.Encode(f, img, &jpeg.Options{Quality: 90})
			if err != nil {
				return fmt.Errorf("第 %d 页 JPG 编码失败：%v", pageNum+1, err)
			}
		default:
			return fmt.Errorf("不支持的图片格式：%s", imgFormat)
		}

		fmt.Printf("第 %d 页转换完成：%s\n", pageNum+1, imgPath)
	}

	return nil
}

func main() {
	// 配置参数
	pdfPath := "./test.pdf"       // 待转换的 PDF 文件
	outputDir := "./pdf_images"   // 图片输出目录
	dpi := 200                    // 分辨率（200 兼顾清晰和性能）
	imgFormat := "png"            // 输出格式

	// 执行转换
	if err := PDFToImage(pdfPath, outputDir, dpi, imgFormat); err != nil {
		fmt.Printf("PDF 转图片失败：%v\n", err)
		os.Exit(1)
	}
	fmt.Println("所有页面转换完成！")
}

2. 高性能优化版（并发转换）​

单页串行转换效率低，针对多页 PDF，用goroutine 并发转换提升性能（控制并发数避免资源耗尽）：

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"sync"

	"github.com/gen2brain/go-fitz"
	"image/jpeg"
	"image/png"
)

// PDFToImageConcurrent 并发 PDF 转图片
// maxWorkers: 最大并发数（根据 CPU 核心数设置，推荐 4-8）
func PDFToImageConcurrent(pdfPath, outputDir string, dpi int, imgFormat string, maxWorkers int) error {
	// 1. 初始化准备
	if err := os.MkdirAll(outputDir, 0755); err != nil {
		return fmt.Errorf("创建输出目录失败：%v", err)
	}

	doc, err := fitz.New(pdfPath)
	if err != nil {
		return fmt.Errorf("打开 PDF 失败：%v", err)
	}
	defer doc.Close()

	totalPages := doc.NumPage()
	fmt.Printf("PDF 总页数：%d，并发数：%d，开始转换...\n", totalPages, maxWorkers)

	// 2. 创建任务通道和等待组
	pageChan := make(chan int, totalPages)
	var wg sync.WaitGroup
	sem := make(chan struct{}, maxWorkers) // 信号量控制并发数

	// 3. 填充任务（页码）
	for pageNum := 0; pageNum < totalPages; pageNum++ {
		pageChan <- pageNum
	}
	close(pageChan)

	// 4. 启动并发任务
	for pageNum := range pageChan {
		wg.Add(1)
		sem <- struct{}{} // 获取信号量

		go func(p int) {
			defer wg.Done()
			defer func() { <-sem }() // 释放信号量

			// 渲染页面
			img, err := doc.Image(p, dpi)
			if err != nil {
				fmt.Printf("第 %d 页渲染失败：%v\n", p+1, err)
				return
			}

			// 保存图片
			imgName := fmt.Sprintf("%d.%s", p+1, imgFormat)
			imgPath := filepath.Join(outputDir, imgName)

			f, err := os.Create(imgPath)
			if err != nil {
				fmt.Printf("第 %d 页创建文件失败：%v\n", p+1, err)
				return
			}
			defer f.Close()

			// 编码图片
			switch imgFormat {
			case "png":
				if err := png.Encode(f, img); err != nil {
					fmt.Printf("第 %d 页 PNG 编码失败：%v\n", p+1, err)
				}
			case "jpg":
				if err := jpeg.Encode(f, img, &jpeg.Options{Quality: 90}); err != nil {
					fmt.Printf("第 %d 页 JPG 编码失败：%v\n", p+1, err)
				}
			}

			fmt.Printf("第 %d 页转换完成：%s\n", p+1, imgPath)
		}(pageNum)
	}

	// 5. 等待所有任务完成
	wg.Wait()
	return nil
}

func main() {
	// 配置参数
	pdfPath := "./test.pdf"
	outputDir := "./pdf_images_concurrent"
	dpi := 200
	imgFormat := "png"
	maxWorkers := 6 // 并发数（根据服务器 CPU 核心数调整）

	if err := PDFToImageConcurrent(pdfPath, outputDir, dpi, imgFormat, maxWorkers); err != nil {
		fmt.Printf("PDF 转图片失败：%v\n", err)
		os.Exit(1)
	}
	fmt.Println("所有页面转换完成！")
}

三、关键优化点（高性能核心）​

1. 并发控制​

  • 用信号量（semaphore） 限制并发数，避免同时渲染过多页面导致内存溢出；
  • 推荐并发数 = CPU 核心数 × 1.5（如 8 核 CPU 设 12）。

2. 分辨率调优​

  • DPI 越高，图片越清晰，但渲染时间和文件体积呈指数增长：
    • 预览场景：150 DPI（平衡速度和画质）；
    • 高清打印：300 DPI；
    • 低性能设备：100 DPI。

3. 内存优化​

  • 及时关闭 fitz.Document 和文件句柄（defer Close()）；
  • 避免一次性加载大 PDF 到内存，go-fitz 支持按页懒加载，无需手动处理。

4. 格式选择​

  • PNG：无损压缩，画质高，体积大（适合文字类 PDF）；
  • JPG：有损压缩，体积小，画质略低（适合图片类 PDF）；
  • 批量转换时，JPG 比 PNG 快 20%-30%（编码耗时更短）。

5. 预编译与静态链接​

生产环境编译时，静态链接 MuPDF 库，避免部署时依赖系统库：

# Linux/macOS 静态编译
CGO_ENABLED=1 go build -ldflags "-s -w" -o pdf2img .

四、常见问题与避坑指南​

1. 中文乱码/字体缺失​

  • 问题：PDF 中的中文字体未嵌入，渲染时找不到字体导致乱码；
  • 解决：
    1. 将系统中文字体（如 SimSun.ttf）放入 MuPDF 字体目录；
    2. 或在代码中指定字体路径： 
      // 自定义字体路径（示例）
      fitz.SetFontDir("/usr/share/fonts/chinese/")

2. 大 PDF 内存溢出​

  • 问题：转换 1000+ 页 PDF 时内存飙升；
  • 解决：
    1. 降低并发数；
    2. 分批次转换（如每 100 页一批，转换完一批释放资源）；
    3. 限制单页渲染的最大内存（go-fitz 可通过参数设置）。

3. 跨平台部署问题​

  • Windows：需将 MuPDF 的 mupdf.dll 放入可执行文件同目录；
  • Linux：静态编译时需带上 libmupdf.a 静态库；
  • macOS：用 brew install mupdf 安装后，直接编译即可。

4. 转换速度慢​

  • 排查：
    1. 检查是否开启并发（串行转换速度仅为并发的 1/N）；
    2. 降低 DPI（如从 300 降到 200，速度提升 50%）；
    3. 改用 JPG 格式（比 PNG 编码快）。

五、扩展功能（实用补充）​

1. 指定页码范围转换​

// 仅转换第 1-10 页
for pageNum := 0; pageNum < 10; pageNum++ {
    pageChan <- pageNum
}

2. 图片压缩​

转换后用 github.com/disintegration/imaging 压缩图片：

go get github.com/disintegration/imaging
// 压缩图片到指定尺寸
img = imaging.Resize(img, 1920, 0, imaging.Lanczos)

3. PDF 转单张长图​

将所有页面拼接为一张长图（适合电子书）：

// 核心逻辑：计算总高度 → 创建新画布 → 逐页拼接
totalHeight := 0
for pageNum := 0; pageNum < totalPages; pageNum++ {
    img, _ := doc.Image(pageNum, dpi)
    totalHeight += img.Bounds().Dy()
}

// 创建长图画布
longImg := image.NewRGBA(image.Rect(0, 0, img.Bounds().Dx(), totalHeight))
y := 0
for pageNum := 0; pageNum < totalPages; pageNum++ {
    img, _ := doc.Image(pageNum, dpi)
    // 绘制到长图
    draw.Draw(longImg, img.Bounds().Add(image.Pt(0, y)), img, image.Point{}, draw.Src)
    y += img.Bounds().Dy()
}

// 保存长图
f, _ := os.Create("./long_image.png")
png.Encode(f, longImg)

总结​

  1. 核心选型：高性能场景优先用 go-fitz（基于 MuPDF），轻量无依赖场景用 pdfcpu；
  2. 性能优化：并发转换（信号量控并发）+ 合理 DPI + 及时释放资源是关键；
  3. 避坑重点：解决中文乱码需配置字体，大 PDF 转换要分批次/降并发；
  4. 扩展能力：支持指定页码、图片压缩、拼接长图等实用功能。