go-wkhtmltopdf完全指南：用Golang轻松生成PDF文档的终极方案
项目地址: https://gitcode.com/gh_mirrors/go/go-wkhtmltopdf go-wkhtmltopdf是一个功能强大的Golang命令行包装器，专为wkhtmltopdf工具设计，帮助开发者轻松实现从HTML到PDF的高效转换。无论是生成定制化发票、复杂报表还是图文并茂的文档，这个工具都能满足你的需求，让PDF生成过程变得简单而高效。
🚀 为什么选择go-wkhtmltopdf？
在现代应用开发中，PDF文档生成是许多业务场景的必备功能。go-wkhtmltopdf通过将强大的wkhtmltopdf工具与Golang的简洁高效相结合，为开发者提供了以下核心优势：
- 类型安全的API：所有选项都通过结构体成员实现，配合IDE的代码补全功能，让开发过程更加流畅
- 灵活的输入输出：支持多种输入源（URL、本地文件、内存数据）和输出方式（内存缓存、直接写入磁盘、自定义Writer）
- 精细的PDF控制：通过丰富的配置选项，精确控制PDF的布局、样式和行为
- 服务器友好设计：每个PDF生成实例拥有独立的输出缓冲区，适合并发环境使用
⚙️ 快速安装指南
前提条件
在使用go-wkhtmltopdf之前，需要确保系统中已安装wkhtmltopdf工具。你可以从wkhtmltopdf官方网站下载适合你操作系统的版本。
安装go-wkhtmltopdf
使用Go模块管理工具，只需一行命令即可完成安装：
go get -u github.com/SebastiaanKlippert/go-wkhtmltopdf
go-wkhtmltopdf会自动查找wkhtmltopdf可执行文件的路径，查找顺序如下：
- 当前目录
- 系统PATH环境变量中的目录
- WKHTMLTOPDF_PATH环境变量指定的路径
如果需要手动设置路径，可以使用SetPath()方法进行配置。
💡 入门示例：生成你的第一个PDF
下面是一个简单的示例，展示如何使用go-wkhtmltopdf从网页URL生成PDF文档：
package main
import (
"log"
"github.com/SebastiaanKlippert/go-wkhtmltopdf"
)
func main() {
// 创建新的PDF生成器
pdfg, err := wkhtmltopdf.NewPDFGenerator()
if err != nil {
log.Fatal(err)
}
// 设置全局选项
pdfg.Dpi.Set(300) // 设置DPI为300
pdfg.Orientation.Set(wkhtmltopdf.OrientationLandscape) // 横向 orientation
pdfg.Grayscale.Set(true) // 生成灰度PDF
// 创建一个从URL获取内容的页面
page := wkhtmltopdf.NewPage("https://pkg.go.dev/github.com/SebastiaanKlippert/go-wkhtmltopdf")
// 设置页面选项
page.FooterRight.Set("[page]") // 页脚右侧显示页码
page.FooterFontSize.Set(10) // 页脚字体大小
page.Zoom.Set(0.95) // 页面缩放比例
// 将页面添加到PDF生成器
pdfg.AddPage(page)
// 在内部缓冲区中创建PDF文档
err = pdfg.Create()
if err != nil {
log.Fatal(err)
}
// 将缓冲区内容写入磁盘文件
err = pdfg.WriteFile("./example.pdf")
if err != nil {
log.Fatal(err)
}
log.Println("PDF生成成功！")
}
你可以在项目的simplesample_test.go文件中找到更多类似的示例代码。
📝 高级用法：从HTML字符串生成PDF
除了从URL获取内容外，go-wkhtmltopdf还支持直接从HTML字符串生成PDF，这对于动态生成的内容特别有用：
htmlContent := `<!DOCTYPE html>
<html>
<head>
<title>动态生成的PDF</title>
<style>
body { font-family: Arial, sans-serif; }
.header { color: #2c3e50; font-size: 24px; }
</style>
</head>
<body>
<h1 class="header">Hello, PDF!</h1>
<p>这是一个从HTML字符串生成的PDF文档。</p>
</body>
</html>`
// 创建PDF生成器
pdfg, err := wkhtmltopdf.NewPDFGenerator()
if err != nil {
log.Fatal(err)
}
// 添加HTML内容作为页面
pdfg.AddPage(wkhtmltopdf.NewPageReader(strings.NewReader(htmlContent)))
// 设置PDF选项并生成
pdfg.Dpi.Set(600)
err = pdfg.Create()
if err != nil {
log.Fatal(err)
}
// 保存PDF到文件
err = pdfg.WriteFile("./dynamic.pdf")
🔄 JSON序列化功能
go-wkhtmltopdf提供了将PDF配置序列化为JSON的功能，这使得在不同环境之间传输和重建PDF配置变得非常简单：
// 客户端代码：准备PDF配置并序列化为JSON
pdfg := wkhtmltopdf.NewPDFPreparer()
pdfg.AddPage(wkhtmltopdf.NewPageReader(strings.NewReader(htmlContent)))
pdfg.Dpi.Set(600)
jsonBytes, err := pdfg.ToJSON()
if err != nil {
log.Fatal(err)
}
// 服务器代码：从JSON重建PDF生成器并生成PDF
pdfgFromJSON, err := wkhtmltopdf.NewPDFGeneratorFromJSON(bytes.NewReader(jsonBytes))
if err != nil {
log.Fatal(err)
}
err = pdfgFromJSON.Create()
if err != nil {
log.Fatal(err)
}
这种功能特别适用于需要在客户端准备PDF配置，然后在服务器端实际生成PDF的场景，如AWS Lambda环境。
⚠️ 注意事项
- wkhtmltopdf状态：请注意，wkhtmltopdf工具本身已不再维护并在GitHub上归档。虽然go-wkhtmltopdf仍会维护一段时间，但建议新项目考虑寻找替代方案。
- 大型文件处理：对于大型PDF文件，可以使用
SetOutput方法让wkhtmltopdf直接写入磁盘，而不是使用内部缓冲区。 - Go 1.19+兼容性：在Go 1.19及以上版本中，不再允许从当前路径运行可执行文件，需要确保wkhtmltopdf位于系统PATH中或通过环境变量指定路径。
📚 学习资源
- 详细的API文档可以在GoDoc上找到
- 更多复杂用法示例，请查看项目中的wkhtmltopdf_test.go文件
- 对于AWS Lambda部署示例，可以参考go-wkhtmltopdf-lambda项目
通过go-wkhtmltopdf，你可以轻松地在Golang应用中集成强大的PDF生成功能，无论是简单的报告还是复杂的商业文档，都能高效、高质量地完成。现在就开始尝试，体验用Golang生成PDF的便捷与强大吧！
要开始使用，只需克隆仓库：
git clone https://gitcode.com/gh_mirrors/go/go-wkhtmltopdf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
