将HTML模板转换为PDF是很多Web开发场景中的常见需求，wkhtmltopdf作为一款基于WebKit引擎的开源转换工具，能够很好地支持HTML、CSS的渲染，输出符合预期的PDF文件。不过如果参数配置不当，很容易出现中文无法显示、页面布局错乱、内容被截断等问题，掌握正确的参数用法是顺利完成转换的关键。
wkhtmltopdf基础转换参数
最基础的转换只需要指定输入的HTML文件路径和输出的PDF文件路径，不过为了适配不同的HTML模板，还需要添加一些基础参数保证转换正常。
常用的基础参数包括：
- --encoding：指定HTML文件的编码格式，避免中文乱码，一般设置为UTF-8
- --enable-local-file-access：允许加载本地文件，比如HTML中引用的本地CSS、图片资源
- --disable-smart-shrinking：禁用自动缩放，避免页面内容被异常缩小
基础转换的示例代码如下：
# 基础转换命令，输入为本地HTML文件，输出为test.pdf wkhtmltopdf --encoding UTF-8 --enable-local-file-access --disable-smart-shrinking ./template.html ./test.pdf
页面布局相关参数
HTML模板的页面尺寸、边距、方向等布局属性需要通过对应参数设置，否则会出现内容超出页面、边距不符合要求的情况。
| 参数名 | 作用说明 | 示例值 |
|---|---|---|
| --page-size | 设置PDF页面尺寸 | A4、A3、Letter |
| --orientation | 设置页面方向 | Landscape（横向）、Portrait（纵向） |
| --margin-top | 设置上边距 | 20mm、1cm |
| --margin-bottom | 设置下边距 | 20mm、1cm |
| --margin-left | 设置左边距 | 15mm、1cm |
| --margin-right | 设置右边距 | 15mm、1cm |
设置A4纵向页面，边距均为20mm的命令示例如下：
wkhtmltopdf --encoding UTF-8 --enable-local-file-access --page-size A4 --orientation Portrait --margin-top 20mm --margin-bottom 20mm --margin-left 20mm --margin-right 20mm ./template.html ./layout_test.pdf
中文显示与字体参数
很多开发者转换PDF时遇到中文不显示的问题，通常是因为wkhtmltopdf没有找到对应的中文字体，除了在系统中安装中文字体，还可以通过参数指定字体路径。
相关参数说明：
- --fontdir：指定字体文件所在的目录，工具会加载该目录下的所有字体
- --default-font：指定默认的字体名称，比如设置为SimSun对应宋体
如果需要加载本地的字体目录，同时设置默认字体为宋体，示例命令如下：
# 指定字体目录为/usr/share/fonts/win-fonts，默认字体为SimSun wkhtmltopdf --encoding UTF-8 --enable-local-file-access --fontdir /usr/share/fonts/win-fonts --default-font SimSun ./template.html ./font_test.pdf
页眉页脚配置参数
如果需要给PDF添加自定义的页眉页脚，可以使用wkhtmltopdf提供的页眉页脚相关参数，支持直接设置文本内容，也支持加载HTML片段作为页眉页脚。
常用参数包括：
- --header-center：设置页眉居中内容
- --header-html：指定页眉的HTML文件路径
- --footer-center：设置页脚居中内容，一般用来显示页码
- --footer-html：指定页脚的HTML文件路径
- --header-spacing：设置页眉和正文之间的间距
- --footer-spacing：设置页脚和正文之间的间距
添加居中页眉为文档标题，页脚居中显示页码的示例命令如下：
wkhtmltopdf --encoding UTF-8 --enable-local-file-access --header-center "HTML转PDF测试文档" --header-spacing 5mm --footer-center "[page]" --footer-spacing 5mm ./template.html ./header_footer_test.pdf
完整转换示例
结合上述所有常用参数，一个完整的HTML模板转PDF的命令示例如下，适配大多数常规HTML模板的转换需求：
wkhtmltopdf --encoding UTF-8 --enable-local-file-access --disable-smart-shrinking --page-size A4 --orientation Portrait --margin-top 20mm --margin-bottom 20mm --margin-left 15mm --margin-right 15mm --fontdir /usr/share/fonts/win-fonts --default-font SimSun --header-center "业务报表" --header-spacing 5mm --footer-center "第[page]页 共[topage]页" --footer-spacing 5mm ./report_template.html ./final_report.pdf
如果是在代码中调用wkhtmltopdf，比如使用Python的subprocess模块执行命令，示例代码如下：
import subprocess
def html_to_pdf(html_path, pdf_path):
cmd = [
"wkhtmltopdf",
"--encoding", "UTF-8",
"--enable-local-file-access",
"--disable-smart-shrinking",
"--page-size", "A4",
"--orientation", "Portrait",
"--margin-top", "20mm",
"--margin-bottom", "20mm",
"--margin-left", "15mm",
"--margin-right", "15mm",
"--default-font", "SimSun",
"--footer-center", "第[page]页 共[topage]页",
html_path,
pdf_path
]
try:
subprocess.run(cmd, check=True)
print("PDF转换成功")
except subprocess.CalledProcessError as e:
print(f"转换失败，错误信息：{e}")
# 调用函数
html_to_pdf("./template.html", "./output.pdf")
注意事项
在使用wkhtmltopdf转换HTML时，还需要注意以下几点：
- HTML中的CSS尽量使用内联样式或者<style>标签写在HTML内部，外部CSS文件可能会出现加载失败的情况
- 如果HTML中有图片，尽量使用绝对路径或者base64编码嵌入，避免相对路径引用失败
- wkhtmltopdf对部分CSS3属性支持有限，复杂的动画、flex布局可能会出现渲染异常，建议转换前简化HTML的样式
- 转换动态HTML时，可以添加
--javascript-delay参数设置JS执行等待时间，确保页面渲染完成后再转换
注意：如果HTML模板中引用了ipipp.com域名的资源，转换时需要保证网络可访问，或者将资源下载到本地后通过本地路径引用。
wkhtmltopdfHTML转PDFPDF参数配置页面尺寸设置页眉页脚配置修改时间：2026-07-17 09:27:37