GitHub Actions中Sphinx运行失败：Ghostscript异常及解决

问题背景 #

• 配置了基于 GitHub Actions 的 Sphinx 文档构建工作流，使用 ubuntu-22.04 镜像，安装 ghostscript 用于将 PDF 图片转换为 PNG 格式
• 本地 Ubuntu 22.04 环境（Ghostscript 9.55.0）运行正常，但在 GitHub Actions 中执行构建时失败

报错信息 #

Extension error:
convert exited with error:
[stderr]
b"Error: /undefined in https:\nOperand stack:\n   (3010)\nExecution stack:\n   %interp_exit   .runexec2   --nostringval--   --nostringval--   --nostringval--   2   %stopped_push   --nostringval--   --nostringval--   --nostringval--   false   1   %stopped_push   1990   1   3   %oparray_pop   1989   1   3   %oparray_pop   1977   1   3   %oparray_pop   1833   1   3   %oparray_pop   --nostringval--   %errorexec_pop   .runexec2   --nostringval--   --nostringval--   --nostringval--   2   %stopped_push   --nostringval--\nDictionary stack:\n   --dict:771/1123(ro)(G)--   --dict:0/20(G)--   --dict:75/200(L)--\nCurrent allocation mode is local\nCurrent file position is 14\nGPL Ghostscript 9.55.0: Unrecoverable error, exit code 1\nconvert-im6.q16: no images defined `/home/runner/work/open-interfaces/open-interfaces/docs/build/doctrees/images/ivp_burgers_soln_scipy_ode_dopri5.png' @ error/convert.c/ConvertImageCommand/3229.\n"
[stdout]

报错解析 #

• no images defined：Ghostscript 无法生成目标 PNG 文件，核心原因是输入的“PDF 文件”并非有效格式
• /undefined in https:：报错中的 https: 来自 Git LFS 指针文件的头部（LFS 指针文件以 version https://git-lfs.github.com/spec/v1 开头），Ghostscript 将纯文本格式的指针文件当作 PDF 解析，触发语法错误

根源定位 #

仓库中的 PDF 图片由 Git LFS 管理，但 GitHub Actions 拉取代码时仅获取了 LFS 指针文件（纯文本），未检出实际的 PDF 文件内容，导致 Ghostscript 解析失败

解决方案 #

在 GitHub Actions 工作流中添加 Git LFS 检出逻辑，确保实际 PDF 文件被拉取：

方式一：使用 actions/checkout 启用 LFS #

- uses: actions/checkout@v4
  with:
    lfs: true

方式二：手动执行 LFS 命令 #

- name: Checkout code
  uses: actions/checkout@v4

- name: Fetch LFS objects
  run: |
    git lfs install
    git lfs pull

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