17370845950

wkhtmltopdf、Chrome/Edge Headless、weasyprint均可离线转HTML为PDF，前提是HTML及所有依赖（CSS、JS、字体、图片）均为本地资源且路径正确，禁用远程引用与动态网络请求。

用 wkhtmltopdf 直接转本地 HTML（无网络依赖）

只要 HTML 文件不引用远程资源（比如 或 ），wkhtmltopdf 就能完全离线运行。它本质是把本地 WebKit 渲染引擎打包进命令行工具，不走浏览器、不连网络。

• 必须下载对应系统架构的静态二进制版（如 wkhtmltopdf-0.12.6-2-buster-amd64.deb 或 Windows 的 wkhtmltopdf-installer.exe），不要用包管理器装的“精简版”（如 Ubuntu 的 apt install wkhtmltopdf 默认装的是无 QT WebKit 的阉割版，会报 QXcbConnection: Could not connect to display）
• 确保 HTML 中所有路径都用相对路径或 file:// 绝对路径，例如： 或
• 若含中文，务必在 HTML 里声明编码，并加 --encoding utf-8 参数，否则 PDF 中文字乱码

Chrome/Edge Headless 模式（需提前下载好浏览器）

Chromium 内核的浏览器支持离线 PDF 导出，但前提是浏览器本身已安装且不依赖在线更新——也就是说，你得用离线安装包（如 google-chrome-stable_120.0.6099.224-1_amd64.deb）并禁用自动更新。

• 导出命令示例（Linux/macOS）：

  chromium-browser --headless --disable-gpu --print-to-pdf="/path/output.pdf" "file:///path/input.html"

• Windows 上注意路径写法：

  chrome.exe --headless --disable-gpu --print-to-pdf="C:\out.pdf" "file:///C:/report/index.html"

• 关键限制：HTML 里不能有 fetch()、XMLHttpRequest 或任何动态加载远程数据的 JS；CSS 和字体也必须本地可读，否则渲染空白
• 首次运行可能弹窗提示“无法连接到网络”，这是 Chromium 检查更新的默认行为，加 --no-sandbox --disable-sync --disable-background-networking 可压制

Python + weasyprint（纯 Python 方案，真正零外部依赖）

weasyprint 是纯 Python 实现的 HTML → PDF 渲染器，底层用 Cairo 和 Pango，不调用浏览器也不联网，适合嵌入脚本或 CI 环境。

• 安装命令：

  pip install weasyprint

• 基础用法：

  from weasyprint import HTML
  HTML('index.html').write_pdf('output.pdf')

• 注意点：不支持 JavaScript、不支持 Flexbox 新语法（如 gap）、CSS Grid 仅部分支持；中文字体必须显式注册，否则显示方块：

  from weasyprint import HTML, CSS
  from weasyprint.fonts import FontConfiguration
  
  font_config = FontConfiguration()
  css = CSS(string='@font-face { src: url("./NotoSansCJKsc-Regular.otf"); font-family: "Noto" } body { font-family: "Noto" }', font_config=font_config)
  HTML('index.html').write_pdf('out.pdf', stylesheets=[css], font_config=font_config)

常见失败原因和绕过方法

不是工具不行，而是 HTML 本身“偷偷联网”或路径失效。遇到空白 PDF、字体缺失、样式错乱，优先排查这些：

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

• → 改成 base64 编码或本地 file:// 路径
• 使用了 Google Fonts 的 → 下载对应 TTF/OTF 字体，用 @font-face 本地加载
• PDF 里图片位置错乱 → 检查 HTML 中图片是否设了

  

  width/height，weasyprint 对 auto 尺寸支持弱，建议显式写死或用 max-width: 100%

真正离线的关键，从来不是选哪个工具，而是 HTML 文件及其全部依赖（CSS、JS、字体、图片）是否物理存在于本地且路径可解析。工具只是执行者，别让它替 HTML 背锅。