使用Sphinx+Furo+Autodoc构建HTML文档时遇样式表配置错误

问题场景 #

使用Sphinx搭配Furo主题构建HTML文档时触发配置错误：

Configuration error:
This documentation is not using `furo.css` as the stylesheet. If you have set `html_style` in your conf.py file, remove it.

但conf.py中未设置html_style参数，依赖通过Poetry安装到.venv虚拟环境，项目内未找到html_style的其他引用。同时想了解是否可以在conf.py中设置自定义样式表。

可能的错误原因及解决办法 #

• 缓存文件干扰：Sphinx生成的_build目录、.doctree等缓存文件可能残留旧主题的样式配置。直接删除_build目录，清理项目内的.pyc缓存文件后重新构建。
• 版本兼容性问题：旧版Furo或Sphinx存在适配bug，导致样式加载异常。用Poetry更新依赖到最新稳定版：

  poetry update sphinx furo
  

• 虚拟环境未激活：构建时未激活Poetry创建的.venv环境，导致全局安装的Sphinx/Furo版本冲突。先激活环境再构建：

  poetry shell
  sphinx-build ...
  

• 自定义模板覆盖配置：_templates目录下的自定义模板（如layout.html）可能覆盖了Furo的样式引入逻辑。若存在自定义模板，需确保正确继承Furo基础模板，在模板开头添加：

  {% extends "!layout.html" %}
  

关于在conf.py中设置自定义样式表的说明 #

可以添加自定义样式表，无需设置html_style，正确步骤：

1. 将自定义CSS文件（如custom.css）放在_static目录下
2. 在conf.py中添加配置：

   html_css_files = [
       'custom.css',
   ]
   

Furo主题会自动加载这些额外样式表，不会覆盖自身的furo.css。

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