wkhtmltopdf、Chrome/Edge Headless、weasyprint均可离线转HTML为PDF，前提是HTML及所有依赖（CSS、JS、字体、图片）均为本地资源且路径正确，禁用远程引用与动态网络请求。
用 wkhtmltopdf 直接转本地 HTML（无网络依赖）
只要 HTML 文件不引用远程资源（比如 <script src="https://cdn.example.com/jquery.js"> 或 <img src="http://...">），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://绝对路径，例如：<link rel="stylesheet" href="./style.css">或<img src="file:///home/user/report/logo.png"> - 若含中文，务必在 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、字体缺失、样式错乱，优先排查这些：
立即学习“前端免费学习笔记（深入）”；
-
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?...>→ 改为本地下载 CSS 并替换 URL，或用@import引入本地文件 - 内联 SVG 含
<image xlink:href="http://...">→ 改成 base64 编码或本地file://路径 - 使用了 Google Fonts 的
<link href="https://fonts.googleapis.com/...">→ 下载对应 TTF/OTF 字体，用@font-face本地加载 - PDF 里图片位置错乱 → 检查 HTML 中图片是否设了
width/height，weasyprint对 auto 尺寸支持弱，建议显式写死或用max-width: 100%
真正离线的关键，从来不是选哪个工具，而是 HTML 文件及其全部依赖（CSS、JS、字体、图片）是否物理存在于本地且路径可解析。工具只是执行者，别让它替 HTML 背锅。
