pdfkit报“No wkhtmltopdf executable found”错，因pdfkit不带渲染引擎，需单独安装wkhtmltopdf并配置PATH；中文乱码需HTML声明UTF-8、指定中文字体、启用local-file-access；动态页面需换Playwright等无头浏览器。
pdfkit.save_file() 为什么报错 No wkhtmltopdf executable found
根本原因是 pdfkit 本身不带渲染引擎，必须单独安装 wkhtmltopdf 二进制程序，并让 Python 找得到它。常见错误现象是调用 pdfkit.from_url() 或 pdfkit.from_string() 时直接抛出 No wkhtmltopdf executable found。
解决办法不是 pip install pdfkit 就完事——那是纯 Python 包，没用：
- macOS：用
brew install wkhtmltopdf；装完后执行which wkhtmltopdf确认路径（通常是/opt/homebrew/bin/wkhtmltopdf或/usr/local/bin/wkhtmltopdf） - Windows：去 官网下载 exe 安装包，勾选「Add to PATH」；若没勾，就手动把安装目录（如
C:\Program Files\wkhtmltopdf\bin）加进系统环境变量PATH - Linux（Ubuntu/Debian）：运行
sudo apt-get install wkhtmltopdf；CentOS/RHEL 用yum install wkhtmltopdf或dnf install wkhtmltopdf
验证是否生效：终端里直接敲 wkhtmltopdf --version 能输出版本号，Python 才可能调用成功。
pdfkit.from_string() 保存中文 HTML 乱码怎么办
核心问题是 wkhtmltopdf 默认不加载中文字体，且 HTML 缺少正确声明。即使源页面用了 UTF-8，PDF 渲染仍会丢字或显示方块。
立即学习“Python免费学习笔记（深入）”；
必须同时满足三个条件：
- HTML 字符串开头显式声明编码：
<meta charset="UTF-8">，不能只靠 HTTP header - 在
<style>中指定支持中文的字体族，例如：body { font-family: "SimSun", "Noto Sans CJK SC", sans-serif; } - 调用
pdfkit.from_string()时传入options参数启用本地字体支持：{"enable-local-file-access": ""}（否则 CSS 文件或本地字体路径会被拒绝）
示例片段：
html = '''
<html>
<head><meta charset="UTF-8">
<style>body { font-family: "SimSun", sans-serif;}</style>
</head>
<body>你好，世界</body>
</html>
'''
pdfkit.from_string(html, 'output.pdf', options={"enable-local-file-access": ""})
用 pdfkit.from_url() 抓取动态渲染页面失败
pdfkit.from_url() 底层调用的是 wkhtmltopdf 的同步快照机制，它不执行 JavaScript。如果你抓的是 Vue/React 渲染的 SPA 页面，或者依赖 AJAX 填充内容的站点，生成的 PDF 很可能只有空壳或 loading 状态。
这不是配置问题，是工具能力边界：
- 不要指望
pdfkit+wkhtmltopdf处理 JS 渲染内容 - 真实需求是“保存最终可视页面”，应换用无头浏览器方案：
playwright或pyppeteer先等 JS 执行完毕，再调用page.pdf() - 如果只是静态 HTML（比如爬虫已拿到完整 HTML 字符串），用
from_string()更可控、更快
顺带一提：wkhtmltopdf 对某些现代 CSS（如 Grid、flex gap）兼容性较差，生成效果可能和浏览器 DevTools 不一致，建议导出前先用 Chrome 手动另存为 PDF 对比。
生成 PDF 文件体积过大或超时崩溃
常见于含大量图片、内联 Base64、或未压缩 CSS/JS 的 HTML。默认情况下 wkhtmltopdf 会尝试加载所有资源（包括远程图片），网络卡顿或资源 404 都会导致超时或空白页。
关键控制点：
- 用
--load-error-handling ignore忽略图片/脚本加载失败（加在options字典里，键为load-error-handling，值为ignore） - 限制图片尺寸：CSS 中强制
img { max-width: 100%; height: auto; }，避免高分屏下原始大图被直接嵌入 - 禁用远程资源：设
options["enable-local-file-access"] = ""并确保 HTML 中所有资源（CSS、字体、图片）都转为本地相对路径或 data URI - 超时时间默认是 0（不限），但实际建议设为
"timeout": "60"（单位秒），防止挂死
真正难搞的是字体嵌入——wkhtmltopdf 不会自动打包 Web 字体（WOFF/WOFF2），必须提前转成系统可读的 TTF/OTF 并用 @font-face 指向本地路径，否则 fallback 字体可能撑大文件或失真。
