WeasyPrint 项目在 macOS 上 Cairo 库加载问题的解决方案

问题背景

在 macOS 系统上使用 WeasyPrint 51 版本生成 PDF 时，可能会遇到 OSError: no library called "cairo-2" was found 的错误。这个问题通常出现在较新的 macOS 系统（如 Sonoma 14.6）上，特别是当使用较旧版本的 Python（如 3.7）和 WeasyPrint 时。

问题分析

WeasyPrint 是一个将 HTML/CSS 转换为 PDF 的工具，它依赖于 Cairo 图形库来渲染页面。在 macOS 上，Cairo 库的加载路径可能会因为系统更新或安装方式的不同而出现问题。

从错误信息可以看出，系统在多个路径中尝试查找以下库文件但均未成功：

• libcairo.so.2
• libcairo.2.dylib
• libcairo-2.dll

解决方案

1. 确认 Cairo 库安装

首先需要确认 Cairo 库是否正确安装。在 macOS 上，可以通过 MacPorts 安装：

sudo port install cairo

安装后，Cairo 库通常位于 /opt/local/lib 目录下。

2. 设置环境变量

为了让 Python 能够找到 Cairo 库，需要设置正确的环境变量。最有效的方法是设置 DYLD_FALLBACK_LIBRARY_PATH：

export DYLD_FALLBACK_LIBRARY_PATH="/opt/local/lib"

这个环境变量告诉系统在哪些额外路径中查找动态链接库。

3. 验证设置

设置环境变量后，可以通过以下命令验证 WeasyPrint 是否能正确识别 Cairo 库：

DYLD_FALLBACK_LIBRARY_PATH="/opt/local/lib" /path/to/your/python -m weasyprint --info

如果设置正确，这个命令应该能正常执行并显示 WeasyPrint 的相关信息。

注意事项

1. Python 版本问题：WeasyPrint 51 版本发布于 2019 年，对 Python 3.7 的支持可能不完善。建议尽可能升级到更新的 Python 和 WeasyPrint 版本。

2. 环境变量作用域：确保环境变量设置在与运行应用程序相同的 shell 会话中。如果通过 IDE 或其他方式运行程序，可能需要在这些环境中单独设置。

3. 安装方式选择：虽然 MacPorts 可以安装 Cairo，但也可以考虑使用 Homebrew 或其他包管理工具，根据项目需求选择最适合的安装方式。

4. ARM64 架构兼容性：在 M1/M2/M3 芯片的 Mac 上，还需要确保安装的 Cairo 库是 ARM64 架构兼容的版本。

总结

解决 WeasyPrint 在 macOS 上找不到 Cairo 库的问题，关键在于确保：

• Cairo 库已正确安装
• 系统能够通过环境变量找到库文件
• 环境变量在正确的上下文中生效

通过合理设置 DYLD_FALLBACK_LIBRARY_PATH 环境变量，大多数情况下可以解决这个问题。对于长期项目，建议考虑升级到更新的 Python 和 WeasyPrint 版本，以获得更好的兼容性和功能支持。