wkhtmltopdf 命令参数及作用大全

wkhtmltopdf 是一款基于 WebKit 引擎的 HTML 转 PDF 工具，支持丰富的命令行参数控制转换过程。以下是常用参数及作用分类说明，方便查阅和使用：

一、基本参数

参数	作用	示例
input.html output.pdf	基础语法：指定输入 HTML 文件（或 URL）和输出 PDF 路径	wkhtmltopdf index.html result.pdf
--version	查看工具版本	wkhtmltopdf --version
--help	查看所有参数说明	wkhtmltopdf --help

二、页面尺寸与布局

参数	作用	示例
--page-size <尺寸>	设置页面尺寸（默认 A4）	--page-size Letter（可选：A3、A4、A5、Legal、Letter 等）
--width <宽度>	自定义页面宽度（单位：mm/cm/in）	--width 210mm
--height <高度>	自定义页面高度	--height 297mm
--orientation <方向>	设置页面方向（纵向 / 横向）	--orientation Landscape（Landscape 横向，Portrait 纵向默认）
--viewport-size <宽x高>	模拟浏览器视口尺寸（解决响应式样式问题）	--viewport-size 1200x800（强制以 1200px 宽度渲染）
--zoom <比例>	页面缩放比例（默认 1.0）	--zoom 0.9（缩小 10%）

三、边距设置

参数	作用	示例
-L/--margin-left <值>	左 margin	-L 10mm 或 --margin-left 1cm
-R/--margin-right <值>	右 margin	-R 0（取消右边距）
-T/--margin-top <值>	上 margin	--margin-top 15mm
-B/--margin-bottom <值>	下 margin	--margin-bottom 2cm

四、样式与渲染控制

参数	作用	示例
--print-media-type	启用 CSS 中 @media print 样式	--print-media-type（优先使用打印样式）
--no-print-media-type	禁用打印样式（默认）	--no-print-media-type
--dpi <值>	设置渲染 DPI（影响图片 / 字体清晰度）	--dpi 300（高清渲染）
--grayscale	生成灰度 PDF（无彩色）	--grayscale
--lowquality	降低质量以减小文件大小	--lowquality
--background	包含背景颜色和图片（默认开启）	--background
--no-background	不包含背景（节省墨水）	--no-background

五、JavaScript 与资源控制

参数	作用	示例
--enable-javascript	启用 JavaScript 执行（默认开启）	--enable-javascript
--disable-javascript	禁用 JavaScript	--disable-javascript
--javascript-delay <毫秒>	等待 JavaScript 执行的时间（解决动态内容渲染问题）	--javascript-delay 5000（等待 5 秒）
--no-stop-slow-scripts	不中断缓慢的脚本（避免脚本未执行完就终止）	--no-stop-slow-scripts
--stop-slow-scripts	中断缓慢的脚本（默认）	--stop-slow-scripts
--enable-local-file-access	允许访问本地文件（如图片、CSS）	--enable-local-file-access（处理本地 HTML 时常用）
--disable-local-file-access	禁止访问本地文件	--disable-local-file-access
--load-error-handling <模式>	处理资源加载错误（ignore/abort/skip）	--load-error-handling ignore（忽略错误继续转换）

六、页眉页脚设置

参数	作用	示例
--header-html <文件>	自定义页眉（通过 HTML 文件）	--header-html header.html
--footer-html <文件>	自定义页脚（通过 HTML 文件）	--footer-html footer.html
--header-center <文本>	页眉居中文本	--header-center "报告标题"
--header-left <文本>	页眉左侧文本	--header-left "日期: 2023-10-01"
--header-right <文本>	页眉右侧文本（支持变量）	--header-right "第 [page] 页 / 共 [topage] 页"
--footer-center/left/right	页脚文本（用法同页眉）	--footer-right "[time]"（显示当前时间）
--header-line	页眉下方添加横线	--header-line
--footer-line	页脚上方添加横线	--footer-line
--header-spacing <值>	页眉与内容的间距（mm）	--header-spacing 5
--footer-spacing <值>	页脚与内容的间距	--footer-spacing 5

页眉页脚变量：[page]（当前页）、[topage]（总页数）、[date]（日期）、[time]（时间）、[title]（页面标题）等。

七、页面内容控制

参数	作用	示例
--exclude-from-outline	排除页面在 PDF 大纲中	--exclude-from-outline
--include-in-outline	包含页面在大纲中（默认）	--include-in-outline
--page-offset <值>	页码偏移（调整起始页码）	--page-offset 2（从第 2 页开始计数）
--no-images	不加载图片	--no-images
--images	加载图片（默认开启）	--images
--disable-smart-shrinking	禁用智能缩放（避免内容被自动缩小）	--disable-smart-shrinking
--enable-smart-shrinking	启用智能缩放（默认）	--enable-smart-shrinking

八、输出控制

参数	作用	示例
--quiet	静默模式（不输出日志）	--quiet
--verbose	详细日志模式	--verbose
--title <标题>	设置 PDF 文档标题	--title "企业风险报告"
--outline	生成 PDF 大纲（书签）	--outline
--no-outline	不生成大纲	--no-outline
--outline-depth <级别>	大纲深度（1-10，默认 4）	--outline-depth 3

九、常用组合示例

1. 转换带动态图表的页面（确保 Echarts/Chart.js 渲染完成）：

   bash

   wkhtmltopdf --enable-javascript --javascript-delay 8000 --print-media-type --viewport-size 1200x800 --enable-local-file-access input.html output.pdf
   

2. 自定义页眉页脚 + 无边缘：

   bash

   wkhtmltopdf -L 0 -R 0 -T 10mm -B 10mm --header-html header.html --footer-right "第 [page]/[topage] 页" input.html output.pdf
   

3. 高清横向 PDF：

   bash

   wkhtmltopdf --page-size A4 --orientation Landscape --dpi 300 input.html output.pdf
   

通过合理组合这些参数，可以解决大部分 HTML 转 PDF 时的样式、渲染、布局问题，尤其适合处理含动态内容（如 JavaScript 生成的图表）或响应式页面的转换场景。