Sphinx生成EPUB时BibTeX参考文献报错求助

问题原因 #

你在EPUB构建命令里用-D extensions=参数覆盖了配置文件的扩展列表，只加载了sphinx.ext.imgmath，但没包含处理BibTeX的扩展。而HTML、LaTeX构建正常，是因为它们沿用了conf.py里已配置的完整扩展列表，自然能识别cite:t角色和bibliography指令。

解决方案 #

有两种可行的处理方式：

方式一：修改EPUB构建命令，补充BibTeX扩展

直接在命令行的extensions参数中加入处理参考文献的扩展（当前主流Sphinx版本用sphinxcontrib.bibtex，旧版本可能是sphinx.ext.bibtex）：

sphinx-build -b epub -D extensions="sphinx.ext.imgmath,sphinxcontrib.bibtex" -D imgmath_embed=True . epub/

方式二：在conf.py中统一配置扩展（更推荐）

打开项目根目录下的conf.py，找到extensions列表，把处理BibTeX的扩展添加进去：

extensions = [
    'sphinx.ext.imgmath',
    'sphinxcontrib.bibtex',
    # 其他你用到的扩展，比如sphinx.ext.autodoc等
]

之后EPUB构建命令可以简化为：

sphinx-build -b epub -D imgmath_embed=True . epub/

额外检查

如果执行后仍报错，先确认已安装sphinxcontrib-bibtex：

pip install sphinxcontrib-bibtex

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