如何加速Jupyter Book构建？并行构建及优化方案咨询

1. Jupyter Book是否原生支持并行构建？ #

不支持。目前所有正式发行版的jupyter-book build命令默认采用单进程顺序调度逻辑，会按目录排序依次完成Notebook执行、格式转换、资源嵌入全流程，官方至今没有把并行构建特性合入稳定版本，没有可直接开启的并行配置参数。

2. 是否可以预先执行完所有Notebook，让构建阶段不重复运行代码？ #

完全可以，这也是官方针对大规模项目首推的优化方案，操作步骤非常明确：

• 提前完成所有Notebook的执行，确保所有.ipynb文件都保存了完整的单元格输出（包括统计结果、可视化图表、打印日志），不要清空输出
• 修改项目根目录下的_config.yml配置文件，关闭构建阶段的代码执行逻辑：

execute:
  execute_notebooks: off

配置生效后再执行构建命令，整个流程只会做格式转换、目录生成、静态资源打包工作，不会重新运行任何Notebook代码，单份Notebook的转换耗时基本在秒级，115份文件的总构建时长通常不会超过10分钟。
预执行阶段可以自行做并行调度，比如写多进程脚本调用jupyter nbconvert --execute、用papermill做参数化并行跑，无算力限制的情况下完全可以达到测算的20分钟全量执行完的效率。

3. 除原生并行、全量预执行外的第三种优化方案 #

有两类可落地的优化方向，适配不同的维护场景：

• 执行缓存方案：不用完全关闭构建阶段的执行逻辑，直接在_config.yml中开启Jupyter Book内置的执行缓存：

execute:
  execute_notebooks: cache
  cache: ./jupyter_cache

开启后构建流程会基于Notebook内容、代码依赖、输入数据的哈希值判断是否需要重新执行，没有变更的Notebook会直接读取历史缓存的输出结果，既避免重复计算，也比全量预执行更适合日常增量更新的场景——后续修改少量Notebook时，不需要重跑全量文件，只执行变更部分即可。

• 重逻辑剥离方案：所有Notebook都是针对不同数据集跑相同逻辑，可以把耗时的计算逻辑从Notebook中抽离，做成独立的离线计算任务，提前跑完把结果存为中间文件（比如结构化数据存parquet、可视化图表存静态图片），Notebook中只保留参数读取、结果展示、少量统计汇总的代码，能直接把单份Notebook的运行时长从20分钟压缩到秒级，从根源上降低构建阶段的计算压力。
  除此之外，构建时可以关闭不必要的动态渲染能力（比如非必要的ipywidgets交互、在线JS资源拉取），也能进一步压缩静态资源处理的耗时。

4. 适配大规模Notebook构建场景的替代工具 #

有三个成熟工具可以选择，迁移成本都不高：

• Quarto：Posit团队开发的开源技术文档工具，原生兼容Jupyter Notebook格式，内置多进程并行执行、增量构建、多级缓存能力，开并行只需要在配置里填要用的CPU核心数，不用自己写调度脚本。支持HTML、PDF、EPUB等多种输出格式，展示效果和Jupyter Book基本一致，百份级Notebook项目是它的常规适用场景，是目前替代Jupyter Book处理大规模项目的首选。
• MkDocs + mkdocs-jupyter插件：MkDocs本身的静态页面生成速度远快于Jupyter Book底层用的Sphinx，搭mkdocs-jupyter插件可以直接渲染带输出的Notebook，也支持执行缓存，适合不需要复杂书籍层级、追求轻量快构的场景。
• nbdev：如果项目除了文档展示，还要绑定代码测试、版本发布这类工程化能力，nbdev内置的并行执行、构建缓存机制也很成熟，适合带生产属性的Notebook项目。

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