图像处理¶
一些 内置插件 依赖于外部库以实现高效的图像处理，最显著的是 社交 插件用于生成 社交卡片，以及 优化 插件用于应用 图像优化。本指南解释了如何在不同环境中安装这些库。
依赖关系¶
图像处理库是完全可选的，仅在您希望使用 社交 插件或 优化 插件时需要安装。库在 imaging 附加项下列出：
这将安装以下软件包的兼容版本：
Cairo 图形¶
Cairo 图形 是一个图形库，也是 Pillow 的依赖项，Material for MkDocs 使用它生成 社交卡片 和执行 图像优化。请参阅以下部分，了解如何在您的系统上安装 Cairo 图形 及其依赖项：
以下环境预装了 Cairo 图形 的版本：
- Docker 镜像 中无需安装
- GitHub Actions (Ubuntu) 中无需安装
pngquant¶
pngquant 是一个优秀的有损 PNG 压缩库，是 内置优化插件 的直接依赖。请参阅以下部分，了解如何安装 pngquant 系统：
确保安装了 Homebrew，这是 macOS 的现代包管理器。接下来，使用以下命令安装所有必要的依赖项：
以下环境预装了 pngquant 的版本：
- Docker 镜像 中无需安装
故障排除¶
找不到 Cairo 库¶
在按照上述安装指南后，您可能仍会遇到以下错误：
no library called "cairo-2" was found
no library called "cairo" was found
no library called "libcairo-2" was found
cannot load library 'libcairo.so.2': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
cannot load library 'libcairo.2.dylib': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
cannot load library 'libcairo-2.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
这意味着 cairosvg 包已安装，但底层的 cairocffi 依赖项无法 找到 已安装的库。根据操作系统，库查找过程有所不同：
Note
在继续之前，请记得完全重启任何打开的终端窗口及其父主机（如 IDE），以重新加载在安装过程中更改的任何环境变量。这可能是快速修复。
在 macOS 上，库查找会检查 dyld 中定义的路径。此外，每个库的 name 会以 三种变体 检查，格式为 libname.dylib、name.dylib 和 name.framework/name。
Homebrew 应该设置每个所需变量以指向已安装的库目录，但如果没有发生，您可以使用下面的调试脚本查看查找的路径。
一个 已知的解决方法 是在运行 MkDocs 之前直接添加 Homebrew lib 路径：
查看 cairo-lookup-macos.py 的源代码
在 Windows 上，库查找会检查环境 PATH 变量中定义的路径。此外，每个库的 name 会以 两种变体 检查，格式为 name 和 name.dll。
UCRT64 环境的默认二进制和共享库路径是：
使用下面的调试脚本检查路径是否包含。如果没有，则：
- 按 Win+R。
- 运行
SystemPropertiesAdvanced小程序。 - 在底部选择“环境变量”。
- 将上述目录的整个路径添加到您的
Path变量中。 - 点击所有打开窗口上的 OK 以应用更改。
- 完全重启任何打开的终端窗口及其父主机（如 IDE）。
查看 cairo-lookup-windows.py 的源代码
在 Linux 上，库查找可能 差异很大，并且依赖于已安装的发行版。对于经过测试的 Ubuntu 和 Manjaro 系统，Python 运行 shell 命令以检查 ldconfig、gcc/cc 编译器和 ld 中可用的库。
您可以使用包含 libcairo.so 等的库目录的绝对路径扩展 LD_LIBRARY_PATH 环境变量。在运行 MkDocs 之前直接运行此命令：
您还可以修改 /etc/ld.so.conf 文件。
下面的 Python 脚本显示了用于查找已安装库的函数。您可以查看源代码以了解在库查找期间在您的系统上执行了哪些特定命令。
查看 cairo-lookup-linux.py 的源代码