如何合并压缩Sphinx扩展的CSS/JS资源以减少HTTP请求？

针对Sphinx构建Read the Docs主题文档时，大量独立CSS/JS资源导致HTTP请求过多的问题，以下是手动和自动两种实现方案：

手动合并压缩步骤 #

1. 定位资源文件：找到Sphinx构建输出目录（默认_build/html/_static）下所有需要合并的CSS/JS，比如copybutton.css、togglebutton.js、pygments.css等。
2. 合并文件：
   • CSS：新建bundle.css，按原加载顺序把所有目标CSS内容复制进去（比如语法高亮的pygments.css建议放在基础样式之后）。
   • JS：新建bundle.js，同样按依赖顺序合并所有目标JS内容（工具类JS优先加载）。
3. 压缩优化：用cssnano（CSS）、terser（JS）这类工具压缩合并后的文件，也可以用在线压缩工具快速处理。
4. 替换页面引用：把RTD主题的base.html模板复制到项目的_templates目录，修改模板里的<link>和<script>标签，将原来的多个资源引用替换成压缩后的bundle.min.css和bundle.min.js。

自动集成方案 #

用sphinxcontrib-webassets扩展自动处理 #

• 先安装依赖：

  pip install sphinxcontrib-webassets cssmin rjsmin
  

• 在项目的conf.py里配置扩展和资源包：

  extensions = [
      # 已有的其他扩展
      'sphinxcontrib.webassets',
  ]
  
  # 定义CSS和JS的合并压缩规则
  webassets_bundles = {
      'css_bundle': {
          'filters': 'cssmin',
          'output': '_static/css/bundle.min.css',
          'contents': [
              '_static/copybutton.css',
              '_static/tabs.css',
              '_static/pygments.css',
              # 补充其他需要合并的CSS路径
          ],
      },
      'js_bundle': {
          'filters': 'rjsmin',
          'output': '_static/js/bundle.min.js',
          'contents': [
              '_static/copybutton.js',
              '_static/togglebutton.js',
              # 补充其他需要合并的JS路径
          ],
      },
  }
  

  构建文档时，该扩展会自动完成合并、压缩，并替换页面中的资源引用。

自定义构建脚本 #

如果现有扩展满足不了需求，可以写一个Python脚本，在sphinx-build完成后执行：

• 用os模块遍历_static目录收集目标资源；
• 用文件操作合并内容；
• 调用cssmin、terser的Python API压缩；
• 用BeautifulSoup解析所有HTML文件，批量替换资源引用标签。

关键注意点 #

• 加载顺序不能乱：必须严格遵循原页面的资源加载顺序，否则会出现样式失效、JS报错的问题。
• 处理缓存：给合并后的文件加版本号（比如bundle.v202405.min.css），避免浏览器缓存旧资源。
• 同步扩展更新：后续更新Sphinx扩展时，要检查是否新增了资源文件，及时调整合并列表。

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