cairosvg 是一个非常强大的库，它可以将 SVG (Scalable Vector Graphics) 文件转换成其他格式的图像，最常见的是 PNG 和 PDF，它的底层依赖是 cairo 图形库。
核心概念：为什么安装有点复杂？
cairosvg 依赖于两个 C 语言库：
- Cairo: 一个强大的 2D 图形库，是 cairosvg 的核心。
- librsvg: 一个用于解析和渲染 SVG 文件的库。
因为 cairosvg 是 Python 的“包装器”，它本身不包含这些 C 库，所以你需要先在你的系统上安装好这些底层依赖，然后再用 Python 的包管理工具（如 pip）安装 cairosvg。
第一步：安装系统依赖 (最关键的一步)
这一步的命令因你的操作系统而异。请务必根据你的操作系统选择对应的命令。
Linux (以 Ubuntu/Debian 为例)
使用 apt-get 安装 cairo 和 librsvg 的开发包。
# 更新软件包列表 sudo apt-get update # 安装 Cairo 和 librsvg 的开发库 sudo apt-get install -y python3-cairo-dev librsvg2-dev
python3-cairo-dev: 提供 Cairo 的 Python 3 绑定和开发头文件。librsvg2-dev: 提供 librsvg 的开发头文件和库。
macOS (使用 Homebrew)
Homebrew 会自动处理依赖关系，安装起来比较简单。
# 使用 Homebrew 安装 cairo 和 librsvg brew install cairo librsvg
安装完成后,pip 通常能自动找到这些库，如果遇到问题，你可能需要设置环境变量 PKG_CONFIG_PATH，但这在大多数情况下是不必要的。
Windows (最复杂)
在 Windows 上手动安装这些依赖比较麻烦。强烈推荐使用预编译的二进制发行版，Anaconda。
使用 Anaconda (推荐)
-
从 Anaconda 官网 下载并安装 Anaconda。
-
安装完成后,打开 Anaconda Prompt (不是普通的 CMD 或 PowerShell)。
-
在 Anaconda Prompt 中，直接使用
conda命令安装，它会自动解决所有依赖问题：conda install -c conda-forge cairosvg
conda-forge是一个社区维护的包频道，提供最新和最全的软件包。
手动安装 (不推荐，仅适合高级用户)
如果你不使用 Anaconda，你需要手动下载预编译的库文件（如 .whl 文件）并配置环境变量，过程非常繁琐，容易出错，对于 Windows 用户，首选 Anaconda。
第二步：使用 pip 安装 cairosvg
在成功安装了上述系统依赖之后,这一步就非常简单了。
打开你的终端 (Linux/macOS) 或 Anaconda Prompt (Windows)，然后运行：
# 推荐使用 pip3 pip3 install cairosvg
或者,如果你使用的是 Python 虚拟环境：
# 激活你的虚拟环境 (venv) source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 然后在激活的环境中安装 pip install cairosvg
第三步：验证安装
安装完成后,你可以通过在 Python 解释器中导入 cairosvg 来验证是否安装成功。
python -c "import cairosvg; print(cairosvg.__version__)"
如果命令输出了 cairosvg 的版本号（5.0），那么恭喜你，安装成功了！
第四步：使用示例
现在我们来试试如何使用 cairosvg，假设你有一个名为 example.svg 的 SVG 文件。
将 SVG 转换为 PNG
import cairosvg
# 输入的 SVG 文件
svg_file = 'example.svg'
# 输出的 PNG 文件
png_file = 'example.png'
# 将 SVG 转换为 PNG 并保存
# dpi (dots per inch) 可以控制输出图像的分辨率
cairosvg.svg2png(url=svg_file, write_to=png_file, dpi=300)
print(f"已将 {svg_file} 转换为 {png_file}")
将 SVG 转换为 PDF
import cairosvg
# 输入的 SVG 文件
svg_file = 'example.svg'
# 输出的 PDF 文件
pdf_file = 'example.pdf'
# 将 SVG 转换为 PDF 并保存
cairosvg.svg2pdf(url=svg_file, write_to=pdf_file)
print(f"已将 {svg_file} 转换为 {pdf_file}")
从字符串转换
你也可以直接从一个包含 SVG 内容的字符串进行转换。
import cairosvg
# 一个简单的 SVG 字符串
svg_string = """
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
<circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" />
</svg>
"""
# 将字符串转换为 PNG 并保存到文件
cairosvg.svg2png(bytestring=svg_string.encode('utf-8'), write_to='from_string.png')
# 也可以直接得到字节流
png_bytes = cairosvg.svg2png(bytestring=svg_string.encode('utf-8'))
# 然后可以将 png_bytes 写入文件或进行其他处理
with open('from_bytes.png', 'wb') as f:
f.write(png_bytes)
常见问题与解决方案 (FAQ)
-
问题:
pip install cairosvg时出现ERROR: Could not build wheels for cairosvg或类似找不到cairo或rsvg的错误。- 原因: 这是最常见的问题，说明你没有成功安装第一步中的系统依赖。
- 解决方案:
- 回到第一步,确保你根据你的操作系统执行了正确的命令。
- Linux/macOS: 确认你使用了
sudo安装，并且包名正确。 - Windows: 强烈建议你切换到使用 Anaconda 的方法，这是最可靠的解决方案。
-
问题: 在 Windows 上，即使安装了 Anaconda，导入时仍然报错。
- 原因: 你可能在错误的 Python 环境中运行代码，请确保你在 Anaconda Prompt 中，并且激活了正确的 conda 环境。
- 解决方案: 使用
conda list cairosvg检查包是否已安装在当前环境中。
| 操作系统 | 推荐安装方法 | 命令 |
|---|---|---|
| Linux (Ubuntu/Debian) | apt-get + pip |
sudo apt-get install python3-cairo-dev librsvg2-dev pip3 install cairosvg |
| macOS | Homebrew + pip |
brew install cairo librsvg pip3 install cairosvg |
| Windows | Anaconda (强烈推荐) | 安装 Anaconda 2. 打开 Anaconda Prompt 3. conda install -c conda-forge cairosvg |
遵循以上步骤,你应该能顺利地在你的 Python 环境中安装并使用 cairosvg。
