Windows环境下利用Sphinx扩展实现SVG转PDF的技术问询

我刚好处理过几乎一模一样的场景，用sphinx.ext.imgconverter完全能实现从同一RST源同时生成HTML和PDF，而且不用修改现有大量SVG图片的引用。下面是分步落地的方案：

1. 安装SVG转换依赖工具 #

Sphinx的imgconverter扩展需要外部工具把SVG转成LaTeX支持的格式（推荐转PDF，能保留矢量图的清晰度），Windows环境首推Inkscape：

• 直接从Inkscape官网下载安装包，安装时一定要勾选「Add Inkscape to system PATH」；如果安装时没勾，后续需要在conf.py里指定工具的绝对路径；
• 也可以用Chocolatey包管理器快速安装：choco install inkscape -y

2. 配置Sphinx的conf.py文件 #

打开项目的conf.py，做以下两处关键配置：

• 启用sphinx.ext.imgconverter扩展：

  extensions = [
      # 保留你已有的其他扩展...
      'sphinx.ext.imgconverter',
  ]
  

• 添加imgconverter的专属配置（适配Windows和Inkscape）：

  # 指定SVG转换工具为Inkscape（如果Inkscape不在PATH里，就写绝对路径，比如r"C:\Program Files\Inkscape\bin\inkscape.exe"）
  imgconverter_converter = 'inkscape'
  # 设置转换参数：把SVG转成PDF（适合LaTeX构建），HTML会直接调用原SVG文件
  imgconverter_args = [
      '--export-type=pdf',
      '--export-dpi=300',  # 按需调整清晰度，数值越高文件越大
      '--export-area-page',
      '{input}',
      '--export-filename={output}'
  ]
  # 可选：构建完成后是否删除转换生成的临时PDF文件（默认False，保留的话下次构建会更快）
  imgconverter_cleanup = False
  

3. 验证与测试 #

• 找一个包含SVG图片的RST文件，比如：

  .. image:: ../images/demo.svg
     :alt: 示例SVG图片
     :width: 80%
  

• 分别执行HTML和PDF构建命令：

  # 构建HTML
  make html
  # 构建PDF（需要确保已安装TeX发行版，比如MikTeX或TeX Live）
  make latexpdf
  

• 检查生成的HTML里是否正常显示SVG，PDF里是否显示转换后的矢量图，无缺失或模糊问题即可。

避坑提示 #

• 如果用的是旧版本Inkscape（0.9x及以前），命令参数要改成--export-pdf={output} {input}，因为新版本的参数格式做了调整；
• 确保所有SVG图片的路径在RST里是正确的，imgconverter会自动识别并处理，完全不用修改原有图片引用；
• Windows下路径注意用正斜杠/或者双反斜杠\\，避免转义报错；
• 如果遇到转换失败，可手动执行Inkscape命令测试，比如inkscape --export-type=pdf input.svg --export-filename=output.pdf，先排查工具本身是否正常工作。

内容的提问来源于stack exchange，提问作者Aleph0