使用Sphinx的WebSupport.build构建文档时如何清除构建缓存？

你遇到的同名图片更新后仍显示旧内容的问题，核心原因是WebSupport默认会复用已有的构建缓存——尤其是图片这类静态资源，它只会检测文件名是否存在，不会自动校验文件内容变化。下面给你几个实用的解决办法：

方法1：手动清空构建目录（等效make clean） #

WebSupport的所有构建产物和缓存都存在你指定的builddir目录里，你可以在每次调用build()前手动清空这个目录，彻底清除旧缓存。

修改你的代码如下：

from sphinxcontrib.websupport import WebSupport
import shutil
import os

srcdir = "你的源目录路径"
builddir = "你的构建目录路径"

# 清空构建目录
if os.path.exists(builddir):
    shutil.rmtree(builddir)
# 重建空的构建目录
os.makedirs(builddir, exist_ok=True)

support = WebSupport(srcdir=srcdir, builddir=builddir, search="xapian")
support.build()
document = support.getdocument("index")

这样每次构建都会从零开始，新图片会完全替换旧文件。

方法2：调用Sphinx原生的clean功能 #

WebSupport底层依赖Sphinx的构建系统，你可以直接调用Sphinx官方的clean命令来清理缓存，这和执行make clean的逻辑完全一致。

代码调整示例：

from sphinxcontrib.websupport import WebSupport
from sphinx.cmd.build import build_main

srcdir = "你的源目录路径"
builddir = "你的构建目录路径"

# 执行clean操作，清理所有缓存产物
build_main(["clean", "-b", "html", srcdir, builddir])

# 正常执行构建流程
support = WebSupport(srcdir=srcdir, builddir=builddir, search="xapian")
support.build()
document = support.getdocument("index")

这个方法更贴合Sphinx的原生逻辑，能确保所有缓存文件（包括隐藏的临时文件）都被彻底清除。

方法3：给图片添加版本标识（长期优化方案） #

如果不想每次构建都清空缓存，你可以给图片文件名添加内容哈希或版本号（比如image-v2.png、image-abc123.png）。这样Sphinx会识别为全新文件，自动替换旧资源，同时还能利用浏览器缓存提升访问性能。

在rst文件里可以这样引用：

.. image:: image-v2.png

你也可以借助工具自动生成带内容哈希的文件名，或者使用Sphinx扩展来自动处理静态资源的版本化，从根源避免缓存冲突问题。

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