企业官网建设流程全解析

mkdocs-material 报 Cairo 库未找到（no library called cairo）怎么处理

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material

在 Material for MkDocs 中启用 social 插件（生成社交卡片）或 optimize 插件（图片优化）后执行构建时，可能遇到这样的报错：

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'

按 image processing 需求指南 的说法，这个错误的含义是：cairosvg包已经安装成功，但它底层的cairocffi依赖在系统里找不到已安装的 Cairo Graphics 库。也就是说 Python 侧的依赖齐了，缺的是系统侧的 Cairo 动态库，或者当前终端的环境变量没有指向它。

确认你确实装了 Cairo 库

报错的前提是已经安装过 Cairo Graphics。如果没有，先按你的操作系统补齐，这些命令来自官方需求指南：

macOS（需先安装 Homebrew）：

brew install cairo freetype libffi libjpeg libpng zlib

Windows（在 MSYS2 的 UCRT64 环境 shell 中执行，这是 MSYS2 开发者推荐的环境）：

pacman -S mingw-w64-ucrt-x86_64-cairo

Linux（按发行版选择）：

# Ubuntu apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev

# Fedora yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel

# openSUSE zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel

Python 侧的依赖通过imagingextra 安装，会同时装好 Pillow 和 CairoSVG 的兼容版本：

pip install "mkdocs-material[imaging]"

两个例外：官方 Docker 镜像和 GitHub Actions（Ubuntu）已经预装了 Cairo Graphics，在这些环境里不需要执行上面的系统包安装步骤。

先做的快速检查：重启终端和 IDE

官方文档给出的第一条建议，成本最低也最容易忽略：安装系统库的过程中往往会改变环境变量，而已经打开的终端（以及 IDE 这类父进程）不会自动加载新变量。在继续往下排查之前，先把所有打开的终端窗口和 IDE 完全重启一次，然后重新运行构建——文档称这一步可能就是快速修复（the quick fix）。

macOS：设置 DYLD_FALLBACK_LIBRARY_PATH

在 macOS 上，库查找会检查 [dyld] 定义的路径，并且每个库名会按libname.dylib、name.dylib和name.framework/name三种变体检查。Homebrew 正常情况下会自动设置好指向已安装库目录的变量，但如果它没做到，文档给出的已知 workaround 是在运行 MkDocs 之前手动导出 Homebrew 的 lib 路径：

export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

如果不确定系统实际在哪些路径里找库，可以运行官方提供的调试脚本 cairo-lookup-macos.py。它会遍历cairo-2、cairo、libcairo-2三个库名的全部变体，逐个打印每个候选路径是Found: <path>还是Doesn't exist: <path>，最后输出：

• The path is <path>（找到时的结果）或The path is not found；
• FFI 实际会尝试加载的文件列表（libcairo.so.2、libcairo.2.dylib、libcairo-2.dll等）。

看到全部路径都是Doesn't exist，说明库路径确实不在 dyld 搜索范围内，此时用上面的DYLD_FALLBACK_LIBRARY_PATH指向实际安装目录。

Windows：把 UCRT64 的 bin 目录加入 Path

在 Windows 上，库查找只检查环境变量PATH中定义的路径，且每个库名按name和name.dll两种变体检查。用 MSYS2 的 UCRT64 环境安装后，Cairo 的默认二进制与共享库路径是：

C:\msys64\ucrt64\bin

先用 PowerShell 确认这个路径是否已在PATH里：

$env:Path -split ';'

如果列表中没有C:\msys64\ucrt64\bin，按文档的步骤补上：

1. 按 ++windows+r++，运行SystemPropertiesAdvanced应用。
2. 在底部选择 "Environmental Variables"。
3. 把上面那个目录的完整路径添加到你的Path变量中。
4. 在所有打开的窗口上点 OK 以应用更改。
5. 完全重启所有打开的终端窗口及其父进程（IDE 等）。

也可以运行官方调试脚本 cairo-lookup-windows.py 直接看每个PATH条目下的查找结果（Found:/Doesn't exist:）以及最终The path is ...的结论，从而确认缺的是哪一个目录。

Linux：扩展 LD_LIBRARY_PATH 或修改 /etc/ld.so.conf

Linux 上的库查找方式因发行版差异很大。文档以经过测试的 Ubuntu 和 Manjaro 为例说明：Python 会运行 shell 命令，依次通过ldconfig、gcc/cc编译器、ld链接器这几个途径检查系统里有哪些可用库。

官方给出的处理方式有两种，任选其一：

把包含libcairo.so等库的目录的绝对路径追加进LD_LIBRARY_PATH，在运行 MkDocs 之前执行：

export LD_LIBRARY_PATH=/absolute/path/to/lib:$LD_LIBRARY_PATH

其中/absolute/path/to/lib是文档中的占位符，需要替换成你系统里libcairo.so所在的库目录的绝对路径（例如用find / -name "libcairo.so.2"定位后填入）。

另一种方式是修改/etc/ld.so.conf文件，把库目录写进去（该文件属于系统级配置，改动影响全机器，需要相应权限）。

要弄清你的发行版具体执行了哪些查找命令，可以运行调试脚本 cairo-lookup-linux.py。它会打印当前LD_LIBRARY_PATH的值，然后对cairo-2、cairo、libcairo-2三个名字分别执行_findSoname_ldconfig、_findLib_gcc、_findLib_ld、_findLib_crle四个查找函数，逐个显示各自的返回结果（Found <path>或无结果），最后给出The path is <path>或The path is not found的总结论以及 FFI 会尝试加载的文件列表。对照这份输出就能判断是LD_LIBRARY_PATH没配，还是库本身没装。

验证修复是否生效

修复是否成功，以重新运行 MkDocs 构建的结果为准：上面那组no library called "cairo"/cannot load library ...报错不再出现。如果报错来自 social 插件生成社交卡片这一步，构建完成后卡片图片会缓存在site目录下（默认是site/assets/images/social），能看到对应页面生成的社交卡片图片，说明 Cairo 链路已经通了。

如果重启终端、设置完环境变量后仍然报同样的错，回到对应平台的调试脚本，确认它最终打印的到底是not found还是某个存在但 FFI 无法加载的路径——前者回到“确认你确实装了 Cairo 库”一节检查系统包是否真的装上了，后者再对照该平台的查找机制（macOS 看 dyld 路径与变体、Windows 看PATH、Linux 看LD_LIBRARY_PATH与ldconfig）逐项核对。

另一点边界：如果你是在 CI 里构建，Docker 镜像和 GitHub Actions 的 Ubuntu 环境自带 Cairo，本地能修好而 CI 里仍报错时，先确认 CI 实际运行的镜像/runner 是否属于这两类预装环境。

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material