怎么将html文件转换为pdf_网页转文档格式方法【工具】

weasyprint 是纯 python 的轻量 pdf 渲染工具，适合静态 html；需处理字体路径、绝对样式链接、避免 unsupported css；puppeteer 依赖 chromium，适合动态内容，但需注意编码、渲染兼容性与字体嵌入问题。

用 weasyprint 直接渲染 HTML 到 PDF，不依赖浏览器

如果你的 HTML 是静态页面、含内联样式或简单 CSS（比如报表、邮件模板），weasyprint 是最轻量且可控的选择。它基于 Python，纯 Python 实现的 CSS 渲染引擎，不启动 Chromium 或 webkit，生成的 PDF 更稳定、更易批量处理。

常见错误现象：WeasyPrint 报 Failed to load stylesheet，其实是相对路径没转成绝对路径；或者中文显示为方块，因为默认没加载中文字体。

• 安装后必须显式指定字体路径：weasyprint input.html output.pdf --fonts /usr/share/fonts/truetype/wqy/wqy-zenhei.ttc
• CSS 中避免用 @import url(...)，改用 <link rel="stylesheet"> 且 href 必须是绝对路径或 base64 内联
• 不支持 position: fixed 用于页眉页脚以外的场景，打印时会错位
• 表格跨页断裂不可控，加 page-break-inside: avoid 仅对块级容器有效，<tr> 上加无效 <h3>用 <code>puppeteer 走 Chromium 渲染，适合动态/交互型 HTML

  如果 HTML 里有 js 初始化图表（如 echarts）、Vue/React 渲染后的内容，或需要截图式精确还原，puppeteer 是更可靠的选择。它本质是控制一个无头 chrome，所以兼容性接近真实浏览器。

  使用场景：导出带 ECharts 的监控看板、含 localStorage 数据的前端管理页、需登录态的内部报告页。

  立即学习“前端免费学习笔记（深入）”；

  • 务必等 JS 执行完成再截取，不能只靠 page.waitForTimeout(2000)，应监听关键 dom 出现：await page.waitForSelector('#chart-container canvas')
  • page.pdf() 默认用 A4 尺寸，但网页宽度超 210mm 会导致横向压缩变形，加 format: 'letter' 或手动设 width/height
  • linux 服务器上运行常报 chrome not found，不是没装 Chrome，而是 puppeteer 下载的 Chromium 权限被 SELinux 拦截，建议用 --no-sandbox 启动，但仅限可信环境
  • PDF 中的超链接默认失效，需加 printBackground: true 和 CSS @media print { a::after { content: ' (' attr(href) ')'; } } 才能保留可读性

  遇到 UnicodeEncodeError 或乱码？先确认 HTML 声明和编码一致

  很多“转 PDF 中文变问号”问题，根源不在工具，而在 HTML 文件本身编码混乱。浏览器能容错，weasyprint 和 puppeteer 却很严格。

  错误现象：UnicodeEncodeError: 'latin-1' codec can't encode character 'u4f60'；或 PDF 里中文全成空白/方框。

  • 检查 HTML 文件开头是否有 <meta charset="utf-8">，且文件实际保存为 UTF-8（无 bom）
  • 用 file -i your.html 确认编码，不是 “us-ASCII” 或 “iso-8859-1”
  • weasyprint 读文件时若没指定 encoding，默认按系统 locale 解码，Linux 服务器常是 en_US.UTF-8，但某些 docker 镜像 locale 是 C，导致 decode 失败
  • 稳妥做法：用 Python 脚本读取 HTML 字符串，显式 .decode('utf-8') 后传给 HTML(String=...)，绕过文件读取环节

  生成 PDF 后字体发虚、线条锯齿？别怪工具，先查 CSS 渲染模式

  PDF 导出后文字边缘模糊、SVG 图标出现灰边、细线断续——这类问题通常不是 DPI 设置低，而是 CSS 中触发了非标准渲染路径。

  典型诱因：用了 transform: scale()、Filter: drop-shadow()、或 backface-visibility: hidden 这类强制硬件加速的属性。

  • weasyprint 完全忽略 transform 和 filter，遇到就静默降级，可能让布局塌陷，间接导致字体重排模糊
  • puppeteer 虽支持，但 PDF 导出时 Chromium 会把 transform 后元素光栅化成位图，分辨率锁定在 96dpi，放大即糊
  • 解决方案：导出前用 JS 移除这些样式：document.querySelectorAll('*').foreach(el => el.style.transform = '')
  • SVG 图标务必用 <svg></svg> 内联，不要 <img src="icon.svg" alt="怎么将html文件转换为pdf_网页转文档格式方法【工具】" >，否则 puppeteer 无法嵌入矢量数据

  字体嵌入、CSS 分页、页眉页脚变量替换这些事，得一层层试，没有一键完美的路径。真正卡住的，往往是 HTML 里某个没意识到的 CSS 特性，在 PDF 渲染链路里被悄悄吞掉了。