企业官网建设流程全解析

wkhtmltopdf 快速指南：一条命令把 HTML 转成 PDF 的完整教程

【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf

wkhtmltopdf 是一个命令行工具，它调用 WebKit 渲染引擎，把 HTML 网页或本地 HTML 文件转换成 PDF 文档，并保留页面的样式、图片与排版。适合批量导出业务报告、保存在线文章、生成带页码和目录的正式文档等场景。

📋 能力速览：wkhtmltopdf 输入输出是什么

• 输入：网页 URL、本地 HTML 文件，一次可传入多个对象
• 输出：PDF 文件；同族工具wkhtmltoimage输出 PNG、JPEG 等图片
• 文档对象：page（普通页面）、cover（封面页）、toc（目录），按命令行顺序排入文档
• 运行方式：无界面（headless）运行，无需显示器
• 可定制项：纸张尺寸、页边距、页眉页脚、缩放比例、目录样式

🚀 三步跑通 wkhtmltopdf 首次转换

第一步：获取 wkhtmltopdf

克隆源码仓库作为构建起点（各发行版通常也提供预编译包）：

git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf

第二步：一条命令转换网页

将本地 HTML 文件转成 PDF，参数只需输入和输出两个位置：

wkhtmltopdf report.html report.pdf

第三步：验证生成的 PDF

确认输出文件已生成并查看其大小：

ls -l report.pdf

文件有实际大小即转换成功，可直接打开查看排版。

按场景配置 wkhtmltopdf 参数

调整页面尺寸与边距

把文档设为 A4 横向、底部留 20mm 边距：

wkhtmltopdf -s A4 -O Landscape -B 20mm input.html output.pdf

生成轻量纯文本版 PDF

去掉图片与 JavaScript，仅保留文字以缩小文件体积：

wkhtmltopdf -n --no-images --lowquality input.html output.pdf

合并多个 HTML 为一个 PDF

指定封面、目录和多个正文页，按顺序合成一本：

wkhtmltopdf cover.html toc page1.html page2.html combined.pdf

🛠️ 避坑指南：中文乱码与图片缺失

中文显示为方框或乱码

现象：PDF 里中文变成小方格。原因：输入编码不是 UTF-8 或系统缺少中文字体。修复：指定编码，并确保系统已安装中文字体。

wkhtmltopdf --encoding UTF-8 input.html output.pdf

PDF 中图片不显示

现象：图片位置空白。原因：本地 HTML 引用的相对路径图片默认不被允许加载。修复：显式开启图片与本地文件访问。

wkhtmltopdf --images --enable-local-file-access input.html output.pdf

版式比浏览器里偏小

现象：内容整体缩小一圈。原因：WebKit 的智能缩放策略改变了像素与 DPI 的换算。修复：关闭智能缩放并锁定纸张尺寸。

wkhtmltopdf --disable-smart-shrinking -s A4 input.html output.pdf

📚 延伸与资源

需要更细的开关时，查阅仓库内自带的参数手册：docs/usage/wkhtmltopdf.txt。

wkhtmltopdf 适合内容相对静态的文档转换；若页面重度依赖动态 JavaScript 交互，渲染结果可能与浏览器存在差异，建议先用最简命令试转一份，再按场景叠加参数。

【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf