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需先安装 Homebrewbrew install cairo freetype libffi libjpeg libpng zlibWindows在 MSYS2 的 UCRT64 环境 shell 中执行这是 MSYS2 开发者推荐的环境pacman -S mingw-w64-ucrt-x86_64-cairoLinux按发行版选择# 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-develPython 侧的依赖通过imagingextra 安装会同时装好 Pillow 和 CairoSVG 的兼容版本pip install mkdocs-material[imaging]两个例外官方 Docker 镜像和 GitHub ActionsUbuntu已经预装了 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还是Doesnt exist: path最后输出The path is path找到时的结果或The path is not foundFFI 实际会尝试加载的文件列表libcairo.so.2、libcairo.2.dylib、libcairo-2.dll等。看到全部路径都是Doesnt 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按文档的步骤补上按 windowsr运行SystemPropertiesAdvanced应用。在底部选择 Environmental Variables。把上面那个目录的完整路径添加到你的Path变量中。在所有打开的窗口上点 OK 以应用更改。完全重启所有打开的终端窗口及其父进程IDE 等。也可以运行官方调试脚本 cairo-lookup-windows.py 直接看每个PATH条目下的查找结果Found:/Doesnt exist:以及最终The path is ...的结论从而确认缺的是哪一个目录。Linux扩展 LD_LIBRARY_PATH 或修改 /etc/ld.so.confLinux 上的库查找方式因发行版差异很大。文档以经过测试的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考