如何处理Sphinx image指令生成内嵌base64图片数据URI的HTML

默认Sphinx编译RST文件时，.. image::指令生成的img标签会引用外部独立图片文件，要实现图片转base64内嵌到HTML中，可通过以下两种方案实现：

方案1：自定义Sphinx扩展（构建时自动处理，推荐） #

该方案在Sphinx构建流程中直接替换图片节点的引用，不需要额外的后处理步骤，适配所有原生image指令和兼容该指令的第三方扩展。

• 在Sphinx项目的conf.py同级目录下，新建名为inline_image_base64.py的文件，写入以下代码：

import os
import base64
import mimetypes
from docutils import nodes
from sphinx.application import Sphinx

def replace_img_with_base64(app: Sphinx, doctree, docname):
    # 遍历文档树中所有图片节点
    for img_node in doctree.traverse(nodes.image):
        img_src = img_node["uri"]
        # 跳过远程图片、已经是base64格式的图片
        if img_src.startswith(("http://", "https://", "data:")):
            continue
        # 按优先级查找图片本地实际路径
        img_abs_path = None
        path_candidates = [
            # 当前RST文档同级的相对路径
            os.path.join(app.srcdir, os.path.dirname(docname), img_src),
            # 项目源目录根路径
            os.path.join(app.srcdir, img_src),
            # 静态资源目录路径
            os.path.join(app.srcdir, "_static", img_src)
        ]
        for path in path_candidates:
            if os.path.isfile(path):
                img_abs_path = path
                break
        if not img_abs_path:
            continue
        # 读取图片二进制内容转base64
        with open(img_abs_path, "rb") as f:
            img_binary = f.read()
        # 自动识别图片MIME类型
        mime_type, _ = mimetypes.guess_type(img_abs_path)
        if not mime_type:
            mime_type = "application/octet-stream"
        b64_content = base64.b64encode(img_binary).decode("utf-8")
        # 替换图片引用为data URI
        img_node["uri"] = f"data:{mime_type};base64,{b64_content}"

def setup(app: Sphinx):
    app.connect("doctree-resolved", replace_img_with_base64)
    return {"version": "0.1", "parallel_read_safe": True}

• 编辑项目根目录的conf.py，找到extensions配置列表，把自定义扩展添加进去：

extensions = [
    # 保留原有其他扩展配置
    "inline_image_base64",
]

配置完成后正常执行make html编译即可，所有本地图片都会自动转为base64格式内嵌到HTML的img标签中。如果你的图片存放在其他自定义目录，只需要在上述代码的path_candidates列表中添加对应的路径拼接规则即可。

方案2：编译后批量处理HTML文件 #

如果不想修改Sphinx构建逻辑，可以在执行完默认的make html编译后，写脚本遍历生成的_build/html目录下所有HTML文件，匹配img标签的本地src路径，读取对应图片转成base64后替换src属性值即可，核心的图片转码逻辑和方案1一致。

注意：Base64编码会让图片体积增大约33%，如果内嵌大量大尺寸图片会导致HTML文件体积过大，拖慢页面加载速度，建议仅对小体积图标、装饰类图片使用该方案。

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