GitLab CI中Sphinx返回错误码-4的原因排查与解决

问题背景 #

本地用Sphinx、tox构建PyScaffold项目文档完全正常，但在GitLab CI的pages任务中执行tox -v -e docs时，进程突然退出并返回错误码-4，无详细错误信息。关键日志片段如下：

[autosummary] generating autosummary for: api/dlproject.data.rst, ..., readme.rst
docs: exit -4 (7.65 seconds) /builds/repo/dlproject> sphinx-build ... pid=346
  docs: FAIL code -4 (361.24=setup[353.59]+cmd[7.65] seconds)

错误原因分析 #

错误码-4对应进程被系统信号终止，结合CI环境特性，最可能的触发场景：

• 内存不足（OOM）：GitLab CI默认runner内存配额有限，Sphinx构建时加载多个intersphinx inventory、生成autosummary会占用大量内存，导致系统强制终止进程。
• 依赖版本隐性冲突：CI环境依赖包版本与本地存在差异，触发非法指令。
• 构建资源配额不足：CPU、内存限制导致进程无法完成资源密集型操作。

具体解决方法 #

1. 优先解决内存问题（最常见） #

• 提升CI资源配额：在.gitlab-ci.yml的pages任务中添加资源配置，申请更多内存：

  pages:
    stage: deploy
    cache: []
    image: "python:3.10-bullseye"
    resources:
      requests:
        memory: "4Gi"  # 按需调整，比如从默认2Gi提升到4Gi
      limits:
        memory: "6Gi"
    script:
      - pip install tox pytest sphinx>=7.0 furo
      - tox -v -e docs
      - mv docs/_build/html public
    artifacts:
      paths:
        - public
  

• 优化Sphinx内存占用：
  • 移除非必要intersphinx链接：在docs/conf.py中注释掉matplotlib、scipy等非核心依赖的intersphinx配置。
  • 缓存intersphinx inventory：在docs/conf.py中启用缓存，避免重复下载大体积文件：

    intersphinx_cache_limit = 5  # 缓存5天
    

  • 减少autosummary开销：设置autosummary_generate_overwrite = False，避免重复生成API文档；或者手动预先生成api目录下的rst文件。

2. 优化tox与CI构建流程 #

• 缓存依赖与构建环境：在.gitlab-ci.yml的pages任务中添加缓存，减少重复安装：

  pages:
    stage: deploy
    cache:
      key: $CI_JOB_NAME
      paths:
        - .tox/docs
        - docs/_build/doctrees
    # 其余配置不变
  

• 简化docs构建步骤：跳过tox隔离，直接在CI脚本中安装依赖并执行构建：

  pages:
    script:
      - pip install -r docs/requirements.txt sphinx>=7.0 furo
      - sphinx-build -T -v --color -b html docs docs/_build/html
      - mv docs/_build/html public
  

3. 排查依赖版本问题 #

• 同步本地与CI依赖版本：将本地生成的requirements.txt或锁文件（如poetry.lock）提交到仓库，强制CI使用一致的依赖版本。
• 降级Sphinx版本：若Sphinx 7.x内存占用过高，尝试降级到6.x版本测试。

4. 调试构建过程 #

• 添加内存监控命令，确认是否发生OOM：

  pages:
    script:
      - free -h
      - pip install tox pytest sphinx>=7.0 furo
      - free -h
      - tox -v -e docs
      - free -h
  

• 启用Sphinx详细日志：在sphinx-build命令中添加-vvv参数，获取更多调试信息。

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