Sphinx生成HTML输出时为何会重复生成图片？

原因 #

• _static目录的图片来源：Sphinx默认会自动扫描文档源目录下的非RST格式文件（如图片、CSS、JS等），将它们复制到输出目录的_static文件夹，这是它的静态文件自动收集机制，和你是否用image:指令引用无关。
• _images目录的图片来源：当你使用image:指令嵌入图片时，Sphinx会单独处理该图片文件，将其复制到_images目录（这是image指令的默认输出路径），生成的HTML也会引用这个目录下的图片。

两种机制同时作用，就导致了图片被复制两次。

解决方法 #

方法1：排除静态文件自动收集的图片 #

在docs/conf.py中添加exclude_patterns配置，让Sphinx不自动复制guide目录下的图片到_static：

exclude_patterns = ['guide/*.jpg', 'guide/*.png']  # 根据实际图片格式调整

这样只有image:指令处理的图片会保留在_images目录，不会出现重复。

方法2：统一图片存放位置 #

将所有图片移到docs/_static目录，然后在RST文件中引用该路径的图片，这样Sphinx不会再将图片复制到_images：

1. 把docs/guide/image.jpg移动到docs/_static/
2. 修改docs/guide/index.rst中的图片引用：

.. image:: ../_static/image.jpg
   :alt: 图片描述

此时生成的HTML会直接引用_static目录下的图片，不会产生重复文件。

方法3：修改image指令的输出目录 #

在docs/conf.py中设置html_image_path，让image:指令处理后的图片直接放到_static目录：

html_image_path = ['_static']

不过这种情况下，建议结合方法1的exclude_patterns一起使用，避免静态文件自动收集机制重复复制同一张图片。

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