html如何兼容低版本转pdf_兼容转html为pdf法【思路】_技术教程

wkhtmltopdf低版本（如0.12.x）因基于旧Qt WebKit内核，不支持Flex/Grid/rem/@media print等现代CSS特性，需降级为table+内联样式、pt单位、绝对路径字体+--font-outline 1等兼容方案。

PDF生成时CSS不生效，是因为wkhtmltopdf默认用Qt WebKit内核

低版本 wkhtmltopdf（如0.12.x）基于旧版Qt WebKit，不支持Flex、Grid、rem单位、@media print中部分属性，甚至会忽略 position: fixed。不是HTML写得不对，是渲染引擎根本没实现。

优先确认你用的 wkhtmltopdf --version 输出版本；0.12.6以下基本不建议用于现代CSS
避免用 display: grid 或 gap —— Qt WebKit 538（对应wkhtmltopdf 0.12.x）完全不识别
font-size: 1.2rem 在某些0.12.x中会被解析为 1.2px，改用 em 或绝对单位（pt 更稳）
用 @media screen 和 @media print 分离样式时，低版本可能只认 @media print，建议统一用后者并禁用屏幕媒体查询干扰

table布局+内联style是低版本最稳的兜底方案

当必须兼容 wkhtmltopdf 0.12.4 或更老版本时，放弃语义化结构和外部CSS，直接用

 + 全内联 style 是最快落地的方案。

所有宽度用 width: 200px 或 width: 30%，不用 max-width（不支持）
边框统一用 border: 1px solid #000，避免 border-collapse: collapse 失效导致双线
文字垂直居中靠 vertical-align: middle + line-height 匹配单元格高，别依赖 flex

图片务必加 height 和 width 属性，否则低版本常渲染为空白或错位

姓名

张三



header/footer在低版本里必须用--header-html参数注入
wkhtmltopdf 低版本不支持HTML内 @page 的 @top-center 等规则，页眉页脚只能通过命令行参数注入独立HTML片段，且该HTML不能含外部CSS或JS。

页眉HTML里只允许内联样式，且不能用 % 单位（如 width: 100% 会失效），推荐固定像素宽
变量如页码需用占位符：第 [page] 页，共 [toPage] 页

如果页眉内容超长换行错位，加 white-space: nowrap + overflow: hidden 控制
注意：--header-spacing 10 才能让页眉和正文保持10px间距，漏掉这个参数会导致页眉压正文

字体嵌入失败？先检查TTF路径和--font-outline参数
低版本 wkhtmltopdf 对中文字体支持极弱，即使指定了 @font-face，也大概率回退到默认无衬线字体。真正起作用的是 --font-outline 参数强制轮廓渲染。

确保TTF文件路径是绝对路径，且wkhtmltopdf进程有读取权限（Docker里尤其注意挂载）
中文必须用TrueType（.ttf），OpenType（.otf）在0.12.x中基本不可用
启动命令里加上 --font-outline 1，这是激活字体轮廓的关键开关，缺了就显示方块
CSS中指定字体时，font-family 值必须和系统注册名一致（如Windows下用 "SimSun"，Linux下用 "WenQuanYi Micro Hei"），不能只写文件名

容易被忽略的一点：生成PDF前，先用 wkhtmltopdf --version 和 wkhtmltopdf --fonts 确认字体列表是否包含你要的中文字体。没有就别折腾CSS了。