GitLab CI中能否借助持久化Docker镜像实现Sphinx增量构建？

我通过GitLab Pages使用Sphinx-doc构建文档，当前的.gitlab-ci.yml配置如下：

image: python:3.10.5-alpine3.16

pages:
  stage: deploy
  script:
  - pip install --verbose --upgrade pip
  - pip install --verbose --upgrade sphinx
  - pip install --verbose --upgrade sphinx_design
  - pip install --verbose --upgrade sphinxext-opengraph
  - pip install --verbose --upgrade sphinx_comments
  - pip install --verbose --upgrade furo
  - pip install --verbose --upgrade myst-parser
  - pip install --verbose --upgrade linkify-it-py
  - sphinx-build --version
  - sphinx-build source build
  - mv build/html public
  artifacts:
    paths:
    - public
  only:
  - master

遇到的问题：哪怕只修改1229个Sphinx（.md）源文件中的一个逗号，GitLab CI里的sphinx-build source build都会全量构建所有HTML页面，耗时约10分钟；但本地终端运行sphinx-build时，只会重建修改对应的页面，仅需数秒。想知道在GitLab上能否通过类似“持久化”的方式实现增量构建。

解决方案：利用GitLab CI缓存机制保存Sphinx中间文件 #

GitLab CI每次运行都是全新的隔离环境，默认不会保留之前的构建缓存，这是导致全量构建的核心原因。Sphinx的增量构建依赖build/.doctrees目录下的中间缓存文件，只要保留这些文件，sphinx-build就能自动检测源文件变化，只构建需要更新的页面。不需要持久化整个Docker镜像，而是通过GitLab的缓存功能保存关键目录即可。

修改后的.gitlab-ci.yml配置 #

image: python:3.10.5-alpine3.16

# 配置缓存：保存pip安装缓存和Sphinx构建中间文件
cache:
  paths:
    - ~/.cache/pip
    - build/.doctrees

pages:
  stage: deploy
  script:
    # 合并依赖安装命令，减少重复步骤
    - pip install --verbose --upgrade pip
    - pip install --verbose --upgrade sphinx sphinx_design sphinxext-opengraph sphinx_comments furo myst-parser linkify-it-py
    - sphinx-build --version
    # 利用缓存的.doctrees目录实现增量构建
    - sphinx-build source build
    - mv build/html public
  artifacts:
    paths:
      - public
  only:
    - master

关键说明 #

1. 缓存Sphinx中间文件：build/.doctrees目录存储了Sphinx构建时生成的语法树缓存，保留这个目录后，后续构建会自动对比源文件的修改时间和缓存记录，只更新变化的页面。
2. 缓存pip依赖：~/.cache/pip目录保存pip下载的包，避免每次CI运行都重新下载所有依赖，减少安装耗时。
3. 第一次构建仍为全量：首次运行时没有缓存，还是会全量构建，但后续提交只要源文件变化小，都会触发增量构建。
4. 强制全量构建的场景：如果修改了Sphinx配置、主题模板或全局依赖，需要手动清理GitLab项目的缓存（在项目设置→CI/CD→缓存中操作），确保全量构建更新所有页面。

内容的提问来源于stack exchange，提问作者Denis Bitouzé