自定义CSS修改Sphinx的sphinx_rtd_theme主题颜色无效，求排查问题

算力阿峰

2026-4-22

兄弟，我来帮你捋捋问题出在哪，大概率是变量名用错了或者缓存/加载顺序的问题，咱们一步步排查：

变量名称不匹配主题规范
sphinx_rtd_theme的CSS变量前缀是--rtd-，不是你用的--sd-！你定义的--sd-color-primary这类变量根本不被主题识别，所以自然还是用默认的蓝色。
改成符合主题规范的变量试试，比如：
```
:root {
  /* 主色调 */
  --rtd-color-primary: #212529;
  /* 主色调深色版本（hover等场景） */
  --rtd-color-primary-dark: #212529;
  /* 链接文本颜色 */
  --rtd-link-color: #212529;
  /* 侧边栏标题文本颜色 */
  --rtd-sidebar-header-text-color: #212529;
}
```
如果需要修改其他元素的颜色，可以去主题的默认CSS里找对应的--rtd-前缀变量。
检查CSS加载顺序与文件路径
确认你的theme.css确实被正确复制到了生成后的_build/html/_static目录里，而且在页面的HTML源码中，自定义CSS的引入是在主题默认CSS之后的——只有这样自定义样式才能覆盖默认样式。
另外检查conf.py里的配置有没有拼写错误，比如html_static_path指向的_static文件夹是否存在，html_css_files里的文件名有没有写错大小写（Linux/Mac下大小写敏感）。
清除Sphinx缓存
有时候Sphinx会缓存旧的构建文件，导致你的CSS修改没生效。直接删掉整个_build文件夹，然后重新执行sphinx-build命令生成文档，确保用的是最新的样式文件。
验证配置完整性
再确认下conf.py里的主题配置是否正确，比如：
```
html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]
html_css_files = [
    'theme.css',
]
```
这部分看起来你写的没问题，但再核对一遍总没错～