当前位置：首页 > 前端开发 > 正文

wkhtmltopdf如何使用

安装后，在命令行执行 wkhtmltopdf 输入.html 输出.pdf，可添加 --page-size A4 等

以下是关于 wkhtmltopdf 的详细使用指南，涵盖安装、基础操作、高级功能及常见问题解决方案：

核心概念与适用场景

wkhtmltopdf 是一款开源的命令行工具，基于 WebKit 引擎实现 HTML→PDF 的高质量转换，其核心优势在于：
完美还原复杂 CSS 布局（含浮动、定位、弹性盒子等）
支持 JavaScript 动态渲染（需配合 --javascript-delay）
可自定义页眉/页脚、页码、目录（TOC）
跨平台兼容（Linux/macOS/Windows）
典型应用场景包括：自动生成电子发票、报告文档、简历模板、网页快照存档等。

安装与环境配置

根据系统选择安装方式

操作系统 安装命令 备注
Ubuntu/Debian sudo apt install wkhtmltopdf 依赖库自动关联
CentOS/RHEL sudo yum install wkhtmltopdf 需启用 EPEL 源
macOS (Homebrew) brew install wkhtmltopdf 推荐最新版
Windows 下载地址：https://wkhtmltopdf.org/downloads.html 选择对应架构的 .exe 文件

验证安装成功

终端执行：wkhtmltopdf --version
正常输出应包含版本号（如 12.6）及编译日期。

基础命令行语法详解

️ 核心参数表

参数 作用 示例值
input 输入文件（HTML/URL） report.html
output 输出 PDF 路径 output.pdf
--page-size 纸张尺寸 A4, Letter
--margin-top 上边距（单位：mm/in/cm/px） 10mm
--orientation 横向/纵向 landscape
--header-center 页眉中央内容 “机密文件 [page]”
--footer-right 页脚右侧内容 “[page]/[topage]”
--enable-local-file-access 允许加载本地资源（安全限制解除） 无

基础示例

# 单文件转换（默认A4纵向）
wkhtmltopdf chapter1.html output.pdf
# 带页眉页脚+横向布局
wkhtmltopdf --orientation landscape 
            --header-center "年度报告" 
            --footer-right "第[page]页/共[topage]页" 
            report.html final_report.pdf

高级功能实践

精准控制页面样式

问题：图片被截断或表格换行异常？
解决方案：通过 CSS 媒体查询强制关键元素不换行：

@media print {
    table { page-break-inside: avoid !important; }
    img { max-width: 100% !important; height: auto !important; }
}

动态内容渲染优化

若页面依赖 AJAX 加载数据,需增加等待时间：

wkhtmltopdf如何使用 第1张

wkhtmltopdf --javascript-delay 1000  # 延迟1秒等待JS执行完毕
            dashboard.html analytics.pdf

自动生成目录（Table of Contents）

要求 HTML 中存在带 ID 的标题标签（h1-h6）,命令如下：

wkhtmltopdf --toc --toc-depth 3  # 生成三级目录
            manual.html user_guide.pdf

生成的目录将位于 PDF 起始位置,点击可跳转至对应章节。

背景图与透明背景处理

  • 添加背景图：在 HTML body 设置 background-image: url('bg.jpg')
  • 透明背景：添加 CSS body { background: transparent !important; } 并禁用默认背景色。

典型错误排查手册

现象 原因分析 解决方案
图片显示为空白/红叉 未正确引用图片路径 改用绝对路径或 Base64 编码内联
中文乱码 缺少中文字体支持 嵌入字体文件（见下文）
分页位置不合理 CSS 未禁止关键元素分页 添加 page-break-inside: avoid
超链接失效 未启用网络访问权限 添加 --enable-local-file-access
页码编号错误 TOC 解析失败 标签有唯一 ID

中文字体嵌入方案

创建 @font-face 规则指向 TTF/OTF 文件：

wkhtmltopdf如何使用 第2张

@font-face {
    font-family: 'SimSun';
    src: url('simsun.ttf') format('truetype');
}
body { font-family: 'SimSun', sans-serif; }

并将字体文件放在与 HTML 同目录下。

编程集成示例（Python）

import subprocess
def html_to_pdf(input_file, output_file):
    cmd = [
        'wkhtmltopdf',
        '--quiet',             # 静默模式（不输出日志）
        '--encoding utf8',     # 防止中文乱码
        input_file,
        output_file
    ]
    subprocess.run(cmd, check=True)
# 调用示例
html_to_pdf('data/invoice.html', 'output/invoice.pdf')

相关问答（FAQs）

Q1: 为什么生成的 PDF 中图片显示不全？

A: 常见原因及解决方法：
1️⃣ 路径问题：HTML 中使用相对路径的图片在 PDF 中可能无法找到，建议改为绝对路径或 Base64 编码。
2️⃣ 尺寸溢出：图片原始尺寸超过页面可用区域，可通过 CSS 设置 max-width: 100%; height: auto; 自适应。
3️⃣ 异步加载延迟：若图片通过懒加载（lazyload）实现，需增加 --javascript-delay 参数给予足够加载时间。

Q2: 如何在 PDF 中实现每页重复的公司LOGO水印？

A: 使用 --header-html 参数指定一个包含LOGO的HTML片段：

wkhtmltopdf如何使用 第3张

wkhtmltopdf --header-html header.html 
            --footer-center "©202X XX公司" 
            contract.html signed_contract.pdf

header.html 内容示例：

<div style="text-align: center;">
    <img src="logo.png" alt="公司LOGO" style="height: 30px;">
</div>

此方法可实现每页顶部固定位置显示LOGO。

通过以上步骤，您已掌握 wkhtmltopdf 的核心功能与实战技巧，如需进一步定制，建议阅读官方文档（https://wkhtmltopdf.org/usage.html）获取完整

wkhtmlto
0

相关文章