GolangHTML转PDF教程全解析

实操建议：

• 仅用于结构极简、无 CSS 依赖的场景，比如日志导出、票据摘要
• 若需保留排版，必须手动把 HTML 拆成 Cell()、MultiCell() 调用，自己算行高和宽度
• 中文需提前注册字体（AddFont() + SetFont()），否则显示方块

chromedp 是目前最靠谱的“HTML → PDF”方案

它通过 DevTools 协议调用本地 Chrome/Chromium，真实渲染页面再导出 PDF，能完整支持 CSS、Flex、媒体查询、字体图标甚至 JS 动态内容。

常见错误现象：

• context deadline exceeded：没加足够超时，或 Chrome 启动失败（缺 --no-sandbox）
• PDF 空白页：HTML 中含 display: none 或未触发重绘（可加 runtime.Evaluate 强制 window.scrollTo(0,0)）
• 中文字体缺失：Chrome 默认不加载系统中文字体，需在 HTML 中显式 @font-face 或用 --font-render-hinting=none

关键参数差异：

• page.PrintToPDF 的 PrintToPDFParams{PaperWidth: 210, PaperHeight: 297} 单位是毫米（A4 尺寸）
• 若 HTML 含相对单位（rem、vh），确保 viewport meta 已设置，否则渲染尺寸异常
• 本地调试时加 chromedp.ExecAllocatorOption(chromedp.Flag("headless", false)) 可看实际渲染过程

别直接用 go-wkhtmltopdf —— 它已停止维护且不兼容新版 wkhtmltopdf

这个包依赖 C 库 wkhtmltopdf，但自 2021 年后没更新，无法适配 wkhtmltopdf 0.12.6+ 的新参数（如 --enable-local-file-access）。编译时容易报 undefined reference to 'wkhtmltopdf_init'。

如果你已有旧项目在用，注意：

• 锁定 wkhtmltopdf 版本为 0.12.5（Ubuntu 20.04 默认源版本）
• Windows 下必须把 wkhtmltopdf.exe 放进 PATH，不能只传绝对路径
• 不支持 HTTP Basic Auth 页面，会卡在认证弹窗（chromedp 可用 network.SetCookies 绕过）

PDF 文件体积大？不是代码问题，是渲染策略问题

chromedp 导出的 PDF 默认含完整字体子集（尤其中文字体），一个页面可能达 10MB+。这不是 Go 写法导致的，而是 Chromium 的默认行为。

减小体积的实操方式：

• HTML 中只 @import 必需字体，避免引入整套思源黑体
• 用 page.PrintToPDF 的 UsePrintDialog: true 参数（仅调试），然后手动勾选 “Background graphics” 关闭背景图
• 导出后用 qpdf --optimize 压缩（额外命令，非 Go 内置）
• 若内容全是文字，考虑先转为 PNG 再用 gofpdf 嵌入——反而更小、更可控

真正难处理的是动态 SVG 或 Canvas 导出：Chromium 渲染后转 PDF 会栅格化，失真不可避免。这时候得回到 HTML 层做降级，比如用 svg-to-pdfkit 替代原生渲染。

今天关于《GolangHTML转PDF教程全解析》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！