想用 Python 生成美观的 PDF 文件？ PDFKit 绝对是个好帮手。 但安装它，可不像看上去那么简单！很多人会踩坑，今天我就来手把手教你，保证一次成功，告别那些烦人的报错。

首先，我们要明确一点：PDFKit 只是一个 Python 库，它本身并不能直接生成 PDF 文件。 它需要依赖一个“渲染引擎”，比如 wkhtmltopdf。 想象一下，PDFKit 是一个画笔，而 wkhtmltopdf 才是颜料，没有颜料，画笔再好也画不出东西。

第一步：安装 wkhtmltopdf

这才是最关键的一步，也是很多人容易出错的地方。wkhtmltopdf 不是 Python 包，不能直接用 pip 安装！

• Windows 系统：

  1. 去 wkhtmltopdf 官网 (https://wkhtmltopdf.org/downloads.html) 下载对应的安装包（一定要根据你的 Windows 系统选择 32 位或 64 位版本）。
  2. 下载后双击安装，一路“下一步”即可。
  3. 最重要的一步！ 安装完成后，需要将 wkhtmltopdf 的安装目录添加到系统的环境变量 PATH 中。 比如，你安装到了 C:\Program Files\wkhtmltopdf\bin，那么就要把这个路径添加到 PATH 环境变量里。 不知道怎么添加？百度一下“Windows 添加环境变量”，有很多教程，照着做就行。 这一步非常重要，不然 PDFKit 找不到 wkhtmltopdf，就会报错。

• macOS 系统：

  macOS 下安装 wkhtmltopdf 相对简单，推荐使用 Homebrew：

  1. 如果还没安装 Homebrew，先安装 Homebrew。 终端输入：

     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. 安装完成后，在终端输入：

     brew install wkhtmltopdf

  Homebrew 会自动帮你下载并配置好 wkhtmltopdf。

• Linux 系统 (以 Ubuntu 为例):

  在终端输入以下命令：

  sudo apt-get update

  sudo apt-get install wkhtmltopdf

  有些情况下，apt-get 安装的版本可能比较旧，如果需要最新版本，可以考虑从官网下载 deb 包手动安装。

第二步：安装 PDFKit

安装完 wkhtmltopdf， 接下来就可以安装 PDFKit 了。 这就简单多了，直接用 pip 命令：

pip install pdfkit

如果你的 Python 环境有多个版本，或者使用了虚拟环境，请确保你在正确的环境下执行 pip install pdfkit 命令。 如果提示权限不足，可以尝试使用 sudo pip install pdfkit（Linux 或 macOS）。

第三步：配置 PDFKit

虽然安装完了 PDFKit，但我们还需要告诉它 wkhtmltopdf 的安装路径。 这一步也很重要，否则 PDFKit 还是会报错。

在你的 Python 代码中，需要进行如下配置：

“`python
import pdfkit

配置 wkhtmltopdf 的路径

config = pdfkit.configuration(wkhtmltopdf=’C:/Program Files/wkhtmltopdf/bin/wkhtmltopdf.exe’) # Windows 示例，请替换成你的实际路径

如果是 macOS 或 Linux，通常不需要配置，PDFKit 会自动找到 wkhtmltopdf

但如果 PDFKit 找不到，也可以手动配置：

config = pdfkit.configuration(wkhtmltopdf=’/usr/local/bin/wkhtmltopdf’) # macOS 示例

config = pdfkit.configuration(wkhtmltopdf=’/usr/bin/wkhtmltopdf’) # Linux 示例

使用配置生成 PDF

pdfkit.from_string(‘

Hello!

‘, ‘out.pdf’, configuration=config)
“`

注意，上面代码中的路径要替换成你实际的 wkhtmltopdf 安装路径。

常见问题和解决方法：

• 报错：IOError: 'No wkhtmltopdf executable found' 或类似错误

  原因：PDFKit 找不到 wkhtmltopdf。

  解决方法：

  1. 确保你已经正确安装了 wkhtmltopdf。
  2. 检查 wkhtmltopdf 的安装路径是否正确，并正确配置 PDFKit。
  3. 检查系统的 PATH 环境变量是否包含了 wkhtmltopdf 的安装目录。

• 生成的 PDF 文件中文乱码

  原因：wkhtmltopdf 默认不支持中文。

  解决方法：

  1. 安装中文字体到系统中，例如：sudo apt-get install fonts-wqy-zenhei （Ubuntu）。

  2. 在生成 PDF 时，指定字体。 可以在 HTML 代码中使用 CSS 指定字体，例如：<style>body { font-family: "WenQuanYi Zen Hei"; }</style>。 也可以在 PDFKit 的配置中指定字体：

     python
options = {
'encoding': 'UTF-8',
'custom-header': [
('Accept-Encoding', 'gzip')
],
'no-pdf-compression': True,
'font-family': 'WenQuanYi Zen Hei' # 注意，这个参数可能不直接生效，推荐在 HTML 中设置
}
pdfkit.from_string('<h1>你好！</h1>', 'out.pdf', options=options, configuration=config)

     或者，在 HTML 头部加入 <meta charset="UTF-8">

• 生成的 PDF 文件样式丢失

  原因：wkhtmltopdf 使用的是一个无界面的浏览器引擎，可能对某些 CSS 特性的支持不够好。

  解决方法：

  1. 尽量使用标准的 CSS 样式。
  2. 避免使用过于复杂的 JavaScript 代码。
  3. 可以尝试调整 wkhtmltopdf 的参数，例如 --disable-javascript、--enable-plugins 等，具体参数可以参考 wkhtmltopdf 的官方文档。

一些小技巧：

• 使用 HTML 模板： 与其直接在 Python 代码中拼接 HTML 字符串，不如使用 HTML 模板引擎（例如 Jinja2），这样可以更方便地管理 HTML 代码和数据。
• 优化 PDF 生成速度： wkhtmltopdf 生成 PDF 文件的速度可能会比较慢，特别是在处理大型 HTML 文档时。 可以尝试使用 --disable-javascript 参数禁用 JavaScript，或者使用 --no-images 参数禁用图片，以提高生成速度。
• 错误处理： 在实际应用中，应该加入错误处理机制，例如使用 try...except 语句捕获异常，并进行相应的处理。

好了，以上就是 Python 安装 PDFKit 的超详细教程。 希望对你有所帮助。 记住，安装 wkhtmltopdf 是关键，一定要仔细阅读文档，按照步骤操作。 祝你使用 PDFKit 愉快！